Saltar al contenido principal

Puertos, tipos y flujo de datos

Esta página explica cómo se transfieren los datos de un nodo a otro en un flujo de trabajo: qué es un puerto, cómo el motor completa las entradas de un nodo, qué tipos de puertos se pueden conectar, cómo una condición poda una rama y cómo se resuelven los marcadores de posición {{NAME}}. Todos los ejemplos que se muestran a continuación se ejecutaron en el motor real con datos sintéticos.

Puedes conectar los nodos en el constructor de flujos de trabajo. Para encontrar los puertos de un nodo en particular, ábrelo en el constructor (Inspector, sección Ports) o en el catálogo de nodos.

Anatomía de un nódulo​

Un nodo tiene tres tipos de cosas:

ParteQué esDónde lo configuraste
ConfigConfiguración que indica al nodo qué hacer (una operación, una URL, un umbral). Fijo para cada ejecución.Inspector, Node Settings
Input portsValores con nombre que el nodo recibe de los nodos ascendentes durante una ejecución. Cada puerto tiene un tipo.Dibuja un borde hacia el puerto
Output portsValores con nombre que produce el nodo. Cada puerto tiene un tipo.Sacar un borde del puerto

En el lienzo, los nombres de los puertos de entrada se muestran a la izquierda de la tarjeta del nodo y los nombres de los puertos de salida a la derecha. Cada puerto es un punto de color (el color refleja el tipo de puerto). Pase el cursor sobre un punto para ver <port name> · <type>.

La mayoría de los nodos tienen dos salidas en común: result (la carga útil, generalmente de tipo json) y success (de tipo boolean). Algunos ejemplos del catálogo:

ID del nodoPuertos de entrada (tipo)Puertos de salida (tipo)
inputinput (cualquiera)output (cualquiera)
conditionfield (cualquiera), context (cualquiera)true (json), false (json), condition_met (booleano), success (booleano)
transforminput (json)result (json), errors (json), error_count (número), success (booleano)
hl7-to-fhirhl7_message (texto)result (json), success (booleano)
fhir-crudresource (json), resource_json (texto), resource_id (texto), bundle (fhir-bundle)result (json), success (booleano)
outputinput (cualquiera)result (json), success (booleano)

Un borde conecta un puerto con otro puerto.​

Una arista se almacena como cuatro valores: nodo de origen, puerto de origen, nodo de destino y puerto de destino. No especifica el nombre de ningún campo dentro de los datos. Cuando se ejecuta el flujo de trabajo, el motor copia el contenido del puerto de origen en las entradas del nodo de destino con el nombre del puerto de destino. Si se necesita un campo específico de ese valor, el nodo receptor debe extraerlo (véase Lectura de datos ascendentes).

Si dibuja una arista sin elegir puertos, el generador almacena los valores predeterminados output (origen) y input (destino).

Tres nodos: el puerto verdadero de un nodo de condición alimenta el puerto de entrada de un nodo de transformación, cuyo puerto de resultado alimenta el puerto de entrada de un nodo de salida. Cada recuadro muestra los datos que transporta el puerto.

Cómo el motor completa las entradas de un nodo​

Antes de que se ejecute cada nodo, el motor construye el inputs de ese nodo examinando cada arista que apunta hacia él. Se aplican tres reglas, en este orden de especificidad:

  1. Par genérico. Una arista del puerto output al puerto input fusiona la salida completa del nodo de origen con las entradas del nodo de destino, clave por clave. Si el origen envolvió su carga útil en result, el motor la desenvuelve primero para que el destino vea las claves internas directamente. success también se transmite.
  2. Par con nombre. Cualquier otro borde copia el valor del puerto de origen al puerto de entrada con el nombre del destino: inputs[target_port] = outputs[source_port].
  3. Si el puerto de origen con nombre no se encuentra en el nivel superior de la salida del origen, el motor lo busca dentro del objeto result del origen. (Por eso una arista de fhir_bundle funciona para un nodo que devuelve su paquete result result.

Las entradas de ejecución (por ejemplo, los valores que se le dan al Run with inputs) también se copian en el inputs de cada nodo antes de que se agreguen las salidas ascendentes.

Entrada en abanico: varios bordes en un solo puerto​

Si varias aristas terminan en el mismo puerto de entrada a través de un par con nombre (regla 2 o 3), los valores no se sobrescriben. Se fusionan:

  • Si ambos valores son objetos de resultado FHIR con un bundle, los arrays bundle.entry se concatenan y se suman los valores numéricos total y count.
  • De lo contrario, los valores se recopilan en una lista, en el orden en que se evaluaron las aristas. Dos nodos de entrada con {x: 1} y {y: 2} conectados desde output a un puerto llamado foo dieron como resultado foo = [{x: 1}, {y: 2}].

Las aristas que usan el par genérico (output a input) no se recopilan. Fusionan clave por clave en las entradas, por lo que cuando dos fuentes llevan la misma clave, la arista evaluada en último lugar gana. Los mismos dos nodos de entrada conectados output al input dieron como resultado {x: 1, y: 2, output: {y: 2}}.

Tipos de puerto​

Cada puerto tiene un tipo, que se muestra como un pequeño chip en la paleta y como una información sobre herramientas en el puerto. Los tipos que aparecen en el catálogo real (198 nodos) son json, text, boolean, number, any, fhir-bundle, binary y string. Las reglas de compatibilidad también definen fhir-resource, hl7-message, x12-message, dicom, ndjson, csv, xml y html.

¿Qué tipos se conectan?​

La regla es una jerarquía sencilla. Un subtipo se conecta a sus tipos padres, y la comprobación es simétrica (se puede conectar en cualquier sentido). any se conecta a todo. Cualquier otro par se conecta solo si ambos puertos tienen exactamente el mismo tipo.

Una jerarquía: fhir-bundle y fhir-resource se conectan a json; hl7-message y ndjson se conectan a json y texto; x12-message, csv, xml y html se conectan a texto; dicom se conecta a binario.

Una salida de tipopuede conectarse a una entrada de tipo
anytodo tipo
jsonjson, fhir-bundle, fhir-resource, hl7-message, ndjson, any
texttext, hl7-message, x12-message, ndjson, csv, xml, html, any
numbernumber, any
booleanboolean, any
binarybinary, dicom, any
fhir-bundlefhir-bundle, json, any
fhir-resourcefhir-resource, json, any
hl7-messagehl7-message, json, text, any
x12-messagex12-message, text, any
dicomdicom, binary, any
ndjsonndjson, json, text, any
csv, xml, htmldel mismo tipo, text, any

Cosas que sorprenden a la gente:

  • fhir-bundle y fhir-resource no están conectados entre sí.
  • text y json no se conectan entre sí. No hay conversión automática. Coloca un nodo entre ellos que genere el tipo que necesitas.
  • Los puertos boolean y number solo se conectan al mismo tipo o a any.
  • Un tipo que no está en la jerarquía (el catálogo tiene algunos puertos de tipo string) se conecta solo al mismo tipo o a any.

Dónde se aplica la norma​

  • Mientras dibujas una arista, el constructor bloquea la conexión entre dos puertos cuyos tipos son conocidos e incompatibles. Si alguno de los puertos es desconocido para el constructor (por ejemplo, un nombre de puerto que no existe), se permite la conexión.
  • Validar (parcialmente). La validación del servidor calcula port type mismatch: <source>.<port> (<type>) → <target>.<port> (<type>) — these port types cannot connect y sugiere entradas de destino que aceptarían el tipo, pero para un flujo de trabajo existente se muestra una advertencia, y el botón Validate de la barra de herramientas solo muestra errores (Valid o Invalid y una información sobre herramientas con los mensajes de error). Por lo tanto, una discrepancia de tipo no hace que el botón se ponga rojo. La validación no marca un nombre de puerto que no existe.
  • En tiempo de ejecución, el motor no verifica los tipos. Copia los valores por nombre de puerto. Una discrepancia de tipos que haya pasado desapercibida (por ejemplo, en un flujo de trabajo escrito en YAML) no es detenida por el ejecutor.

Poda de ramas y nodos omitidos​

Un nodo condition elige una rama. Evalúa su field contra compare_value y emite una lista interna de puertos activos: ["true"] o ["false"]. Luego, el ejecutor recorre todos los demás nodos y aplica una regla:

Un nodo se omite cuando todos sus enlaces entrantes están inactivos. Un enlace está inactivo cuando su nodo de origen también se ha omitido, o cuando su puerto de origen no se encuentra en la lista de puertos activos de dicho nodo. Un nodo sin enlaces entrantes nunca se omite.

Un nodo omitido no se ejecuta y tiene estado skipped (mostrado en el pie de página de la tarjeta del nodo como Skipped). Omisión de propagación: un nodo cuyo único nodo ascendente fue omitido también se omite. Un nodo que tiene al menos una arista entrante activa se ejecuta, por lo que un nodo de unión alimentado por ambas ramas sigue ejecutándose cuando se poda una rama.

Un nodo de condición con puertos activos en falso. El nodo conectado al puerto verdadero se omite, el nodo conectado al puerto falso se ejecuta y el nodo de salida, conectado a ambos, se ejecuta.

Los puertos de un nodo condition transportan por defecto solo una pequeña carga útil: condition_met y un bloque result con branch, compare_value y field_value. Para pasar el registro original por la rama elegida, establezca pass_through en la configuración de la condición como {target_name: input_key}: el valor de la entrada denominada input_key se copia en la rama bajo target_name En el ejemplo siguiente es {record: context}, que copia lo que llegó al puerto context.

Ejemplo práctico: clasificación de resultados de laboratorio​

Este flujo de trabajo tiene un test-patient-a input (defaults: patient_id), jsonpath test potassium 4.2, un nodo path: value (Pick the value), dos nodos condition en map transform compare_value: 5.5 urgent pass_through: {record: context}) que construyen field: value, value y patient a partir input.record.* test y un nodo value alimentado por output. Cada arista usa un puerto condition_type: greater_than el nodo declara. Se ejecutó dos routine en el motor.

Corrercondition puertos activosurgentroutineoutputLo que el nodo output recibió en su puerto input
value = 4.2["false"]omitidoterminadoterminado{patient: "test-patient-a", test: "potassium", value: 4.2}
value = 6.1["true"]terminadoomitidoterminado{patient: "test-patient-a", test: "potassium", value: 6.1}

Los límites, por puerto:

Borde (puerto de origen al puerto de destino)Lo que contiene
input nodo output a jsonpath dataEl récord {patient_id, test, value}
jsonpath value a condition fieldEl número solo (4,2 o 6,1)
input nodo output a condition contextTodo el récord otra vez, para que pass_through pueda llevarlo.
condition false (o true) al input de la transformación{condition_met, result: {branch, compare_value, field_value}, record: {patient_id, test, value}}
transformar result a output input{patient, test, value}

El nodo urgent no tiene entradas ni salidas en la ejecución 4.2: nunca se ejecutó. Un nodo alimentado solo por urgent (un transform adicional conectado al result de urgent) también se omite, y un nodo input sin aristas entrantes sigue funcionando.

Una puerta no puede leer un campo de un registro.

field en un condition nombra la clave que prueba, pero nada resuelve una ruta dentro del valor que llega al puerto field. Conectar el registro directamente a field falla: el motor le entrega al nodo el objeto completo y se detiene con values must be numeric for > comparison. Coloque un nodo que extraiga el valor delante de la puerta (aquí jsonpath) y lleve el registro por separado a través de context Una cadena numérica como "6.1" también falla la comparación numérica. El motor sí acepta una arista a un puerto que el nodo no declara (una arista genérica de output a input extiende el registro en claves de nivel superior), pero el lienzo solo ofrece puertos declarados, por lo que no puede dibujarlo a mano.

nota

Los operadores numéricos requieren números reales. Una cadena numérica como "6.1" (por ejemplo, de un campo de texto) se interpreta como values must be numeric for > comparison. El nodo no convierte cadenas a números.

Lectura de datos ascendentes: la convención input.<field>​

Un nodo transform en modo map recibe sus datos bajo el nombre del puerto al que está conectado. En el ejemplo, la arista termina en el puerto input del nodo routine, por lo que las entradas del nodo son { input: { ... } } y las asignaciones deben comenzar con input.:

config:
transformation_type: map
mappings:
patient: input.patient_id
test: input.test
value: input.value

Sin el prefijo input. los campos mapeados aparecen como null. La misma ruta punteada funciona para datos anidados, por ejemplo input.data.first_name.

{{NAME}} marcadores de posición​

Cualquier cadena en la configuración de un nodo puede contener {{NAME}}. El motor la reemplaza justo antes de que se ejecute el nodo. Los marcadores de posición solo se resuelven en la configuración, no en las aristas ni en los datos que fluyen entre nodos. El motor prueba estas fuentes en este orden, y la primera que conoce el nombre gana:

OrdenSintaxisResuelve a
1{{run.id}}, {{run.pipeline_id}}, {{run.pipeline_version}}, {{run.node_id}}, {{run.started_at}}Datos sobre la ejecución actual (también {{run.run_id}}, igual que run.id).
2{{NAME}} para una credencialEl almacén de credenciales por inquilino, cuando la plataforma tiene uno configurado para su organización.
3{{variable_name}}Una variable no secreta del cajón de Recursos del flujo de trabajo (pestaña Variables).
3{{connectors.<name>.<field>}}Un campo de un conector definido en el panel Recursos (pestaña Connectors). <name> es el nombre o ID del conector.
3{{storage.<name>.<field>}}Un campo de una entrada de almacenamiento (por ejemplo bucket o prefix) de la pestaña Storage.
4{{key}}Un valor de nivel superior en las entradas de tiempo de ejecución del propio nodo (proveniente de un nodo anterior o de las entradas de ejecución). Solo se sustituyen cadenas, números y valores booleanos; no se sustituyen objetos, listas ni valores nulos.

Se deja un marcador de posición que no se resuelve como texto literal, por ejemplo {{MISSING}}. La ejecución no se detiene; el texto literal se envía a quien utilice ese valor.

aviso

Una variable marcada como secreta no se resuelve con {{NAME}}. En el cajón de Recursos, una variable con el interruptor secreto (ojo) activado es rechazada por el resolvedor de marcadores de posición. Un encabezado escrito como Bearer {{FHIR_TOKEN}} con un secreto FHIR_TOKEN llega al sistema de destino como el texto literal Bearer {{FHIR_TOKEN}} Los secretos se resuelven solo a través del almacén de credenciales por inquilino (orden 2). Use una variable no secreta solo para valores que sean seguros de exponer en la definición del flujo de trabajo (por ejemplo, una URL base).

La pestaña Variables también muestra cinco "VARIABLES DEL SISTEMA" ({{pipeline_id}}, {{execution_id}}, {{user_id}}, {{organization_id}}, {{current_timestamp}}). El código del motor que resuelve los marcadores de posición no lee esos nombres. Use {{run.pipeline_id}}, {{run.id}} y {{run.started_at}} en su lugar.

Ejemplo práctico: Mensaje HL7 a FHIR​

Un mensaje sintético ADT^A01 que pasó por hl7-to-fhir produjo un objeto result (tipo json) con estas claves: fhir_bundle, mapping_details, resource_count, resources, source_type, unmapped_segments y warnings. Los únicos puertos de salida del nodo son result y success.

  • fhir_bundle.type es transaction Cada entrada tiene request.method POST y una URL completa de urn:uuid:.
  • El paquete contenía un Paciente (identificador de PID-3, nombre, fecha de nacimiento, sexo) y un Encuentro (clase IMP, estado in-progress, ubicación de PV1-3, referencia del sujeto). NK1 se informó en unmapped_segments.
  • Conectado al puerto bundle de un nodo fhir-crud con operation: transaction, el paquete se envió una vez a la base fhir_url como POST /r4 con Content-Type: application/fhir+json y el encabezado Authorization: Bearer <auth_token>.
  • En un flujo de trabajo YAML, un borde con valor source_port: fhir_bundle funcionó debido al mecanismo de reserva que utiliza el valor result. El lienzo del constructor solo ofrece el puerto result para este nodo.

Los tipos se alinean: result es json y bundle es fhir-bundle, y json se conecta con fhir-bundle.

Cuando algo no fluye​

SíntomaCausaArreglar
La ejecución finaliza como completada, pero un nodo muestra Skipped y se esperaba que se ejecutara.Su conexión entrante se encuentra en un puerto condition que no estaba activo, o bien se omitió su nodo ascendente. Un nombre de puerto mal escrito en una conexión desde un nodo condition se considera inactivo: por ejemplo, una conexión desde un puerto maybe no genera ningún error, la ejecución finaliza y se omite el destino.Abra el borde en el Inspector y verifique el nombre del puerto de origen. Un nodo condition tiene true y false.
Un nodo está en funcionamiento, pero falta un valor esperado.El nombre del puerto de origen del borde no existe en el nodo de origen, por lo que no se copia nada. El motor no informa de un puerto desconocido.Compruebe los nombres de los puertos en el nodo de origen (pase el cursor sobre el punto de un puerto), luego ejecute Debug step-by-step y abra el nodo en la pestaña STEP DEBUG para ver lo que recibió.
values must be numeric for > comparisonSe le proporcionó una cadena de caracteres a un operador numérico.Proporcione un número real (un número JSON, no "6.1").
Los campos mapeados en un transform son null.El mapeo no comienza con el nombre del puerto.Utilice input.<field> cuando el borde termine en el puerto input.
node a (input) failed: required field missing: patient_idEl nodo input tiene required_fields y la ejecución no proporcionó uno.Proporciónelo en Run with inputs o agregue un valor predeterminado.
compilation failed: node release hl7-to-fihr@ is unavailableEl ID del tipo de nodo es incorrecto.Utilice el ID exacto del catálogo de nodos.
compilation failed: connection references non-existent target node: ghostUn enlace apunta a un ID de nodo que no está en el flujo de trabajo.Elimine el borde o corrija la identificación.
compilation failed: failed to determine execution order: circular dependency detected: no nodes with zero in-degreeEl gráfico tiene un ciclo.Elimina el borde que cierra el bucle.
node w (fhir-crud) validation failed: fhir_url is requiredUn campo de configuración obligatorio está vacío.Rellénalo en la oficina del inspector.
Un encabezado o URL muestra el texto {{NAME}} en el sistema receptor.El nombre no se pudo resolver o la variable es secreta.Créela como una variable no secreta o utilice el almacén de credenciales por inquilino para los secretos.

Límites y notas​

  • Los valores se transfieren por nombre de puerto. No hay cableado a nivel de campo, ni conversión automática entre tipos, ni verificación de tipo en tiempo de ejecución.
  • Internamente, el motor libera la copia de trabajo de la salida de un nodo una vez que todos los nodos posteriores la han leído. Esto no elimina nada del resultado de la ejecución: los resultados por nodo siguen mostrando los valores inputs y outputs de cada nodo.

¿Algo no está claro? Envíe sus comentarios sobre la documentación por correo electrónico..