Pragmatic permite la creación de eventos que facilitan la precarga de datos en una instancia de formulario. Estos datos pueden obtenerse desde diferentes fuentes dependiendo del tipo de evento seleccionado: SQL, MongoDB o función JavaScript.

La ejecución del evento ocurre exclusivamente en el momento de ejecución Cargar. Este momento ocurre cuando el usuario accede al formulario por lo que es en este caso donde se busca obtener los datos, cargarlos sobre la instancia y que los datos sean visibles inmediatamente en los campos correspondientes.



Creación de eventos de precarga de datos

Condiciones generales

Para que un evento de precarga de datos funcione correctamente, se deben cumplir los siguientes requisitos:

  1. El evento debe retornar una estructura de respuestas válida según el tipo de evento.
  2. La estructura de respuestas de los campos debe seguir la sintaxis especificada para dicho tipo de evento para el mapeo correcto de los datos.
  3. Una vez creado, el evento debe asociarse al formulario y configurarse en la sección de eventos de un formulario, para ejecutarse en el momento de carga de la instancia de formulario.



Implementación según el tipo de evento

Evento de tipo SQL

Para un evento de tipo SQL, la precarga de datos se implementa mediante una consulta SQL que debe retornar un único registro. Los nombres de las columnas en la consulta deben coincidir con los IDs o nombres únicos de los campos del formulario.

Condiciones específicas:

  • Se debe obtener obligatoriamente un solo registro en los resultados de la consulta.
  • Se debe especificar como nombre de columna el ID o el nombre único del campo al cual se va a cargar el dato.

Ejemplo: 

SELECT 
    id as "banco-id",  -- Se puede usar nombre único o ID numérico (ej: "20")
    abono_mensual as "banco-abonoMensual", 
    nombre as "20",  -- Usando ID numérico en lugar de nombre único
    descripcion as "banco-descripcion", 
    porcentaje_promocion as "banco-porcentajePromocion", 
    fecha_promocion as "banco-fechaPromocion" 
FROM bancos 
WHERE id = @parameter.idBanco



Tipos de campos soportados y su sintaxis:

Tipo de CampoSintaxisEjemplo de Valor
TextoDebe ser un string"Juan Carlos Pérez González"
Texto largoDebe ser un string"Motivo 1: El proyecto requiere una inversión inicial mayor a la presupuestada.\nMotivo 2: Los tiempos de entrega no son viables según el cronograma propuesto."
NúmeroDebe ser un valor numérico42 o 3.14
PorcentajeDebe ser un string numérico entre 0 a 100"75" o "99.9"
FechaDebe ser un string con formato ISO 8601"2024-04-08T00:00:00.000Z"



Evento de tipo MongoDB

Para un evento de tipo MongoDB, la precarga de datos se implementa mediante una consulta de agregación que debe retornar un único documento.

La estructura de retorno debe ser la misma que se utiliza en el evento de tipo función JavaScript, es decir, un arreglo de objetos donde cada objeto contiene O uniqueName O id (no ambos) y value. Para más detalles sobre la estructura de los valores según el tipo de campo, consulta la sintaxis de campos soportados.

Condiciones específicas:

  • Se debe obtener obligatoriamente un solo documento en los resultados
  • La consulta debe transformar los datos para retornar un arreglo de objetos con la estructura:
    [
  {
    "uniqueName": "nombre-campo",  // O usar "id"
    "value": valor
  }
]

Ejemplo: 

[
  // 1. Filtramos el documento por ID
  { $match: { _id: ObjectId(@parameter._id) } },
  
  // 2. Convertimos el _id a string para evitar problemas de serialización
  { 
    $addFields: { 
      _id: { $toString: "$_id" } 
    } 
  },
  
  // 3. Convertimos el documento en un array de pares clave-valor
  { 
    $project: {
      kv: { $objectToArray: "$$ROOT" }
    }
  },
  
  // 4. Mapeamos cada campo a la estructura requerida
  {
    $project: {
      mapped: {
        $map: {
          input: "$kv",
          as: "field",
          in: {
            uniqueName: {
              $switch: {
                branches: [
                  { case: { $eq: ["$$field.k", "_id"] },   then: "usuario-id" },  // Se puede usar nombre único o ID numérico
                  { case: { $eq: ["$$field.k", "nombre"] },   then: "20" },  // Usando ID numérico en lugar de nombre único
                  { case: { $eq: ["$$field.k", "apellido"] }, then: "usuario-apellidos" },
                  { case: { $eq: ["$$field.k", "correo"] }, then: "usuario-correoElectronico" },
                  { case: { $eq: ["$$field.k", "celular"] }, then: "usuario-celular" },
                  { case: { $eq: ["$$field.k", "fechaNacimiento"] }, then: "usuario-fechaNacimiento" },
                  { case: { $eq: ["$$field.k", "promedioSemestral"] }, then: "usuario-promedioSemestral" },
                  { case: { $eq: ["$$field.k", "nivelEstudios"] }, then: "usuario-nivelEstudios" },
                  { case: { $eq: ["$$field.k", "activo"] }, then: "usuario-activo" },
                  { case: { $eq: ["$$field.k", "tareasPorRealizar"] }, then: "usuario-tareas" },
                  { case: { $eq: ["$$field.k", "eventoPorAsistir"] }, then: "usuario-evento" },
                  { case: { $eq: ["$$field.k", "invitacion"] }, then: "usuario-invitacion" }
                ],
                default: null
              }
            },
            value: "$$field.v"
          }
        }
      }
    }
  },
  
  // 5. Limpiamos la estructura para obtener solo los datos mapeados
  { 
    $project: { 
      _id: 0, 
      data: "$mapped" 
    } 
  },
  
  // 6. Expandimos el array en documentos individuales
  { $unwind: "$data" },
  
  // 7. Reemplazamos la raíz con cada documento mapeado
  { $replaceRoot: { newRoot: "$data" } }
]

En este ejemplo:

  1. Se filtra el documento por ID
  2. Se convierte el _id a string para evitar problemas de serialización
  3. Se transforma el documento en un array de pares clave-valor
  4. Se mapea cada campo a la estructura requerida usando $switch para asignar los nombres únicos
  5. Se limpia la estructura para obtener solo los datos mapeados
  6. Se expande el array en documentos individuales
  7. Se reemplaza la raíz con cada documento mapeado

El resultado final será un arreglo de objetos con la estructura:

[
  {
    "uniqueName": "usuario-id",
    "value": "507f1f77bcf86cd799439011"
  },
  {
    "uniqueName": "banco-nombre",
    "value": "Juan"
  },
  // ... más campos
]



Evento de tipo Función JavaScript

Para un evento de tipo función JavaScript, la precarga de datos se implementa mediante una función que debe retornar un arreglo de objetos con la estructura de respuestas.

La estructura de retorno debe ser la misma que se utiliza en el evento de tipo MongoDB, es decir, un arreglo de objetos donde cada objeto contiene O uniqueName O id (no ambos) y value. Para más detalles sobre la estructura de los valores según el tipo de campo, consulta la sintaxis de campos soportados.

Condiciones específicas:

  • La función debe retornar un arreglo de objetos
  • Cada objeto debe contener:
    • uniqueName O id: Identificador del campo al cual se hará el mapeo. Se debe usar uno u otro, no ambos
    • value: El valor correspondiente al campo, que debe seguir la estructura correspondiente al tipo de campo
  • El valor debe seguir la estructura correspondiente al tipo de campo

Ejemplo: 

// 1. Obtenemos los datos necesarios
const idBanco = @parameter.idBanco

// 2. Realizamos la petición a la API
return axios.get(`https://api.ejemplo.com/bancos/${idBanco}`)
.then((response) => {
    const banco = response.data
    
    // 3. Retornamos la estructura de respuestas
    return [
        {
            "uniqueName": "banco-id",  // Usando nombre único
            "value": banco.id
        },
        {
            "uniqueName": "banco-abonoMensual",  // Usando nombre único
            "value": banco.abono_mensual
        },
        {
            "id": 20,  // Usando ID numérico
            "value": banco.nombre
        },
        {
            "uniqueName": "banco-descripcion",  // Usando nombre único
            "value": banco.descripcion
        },
        {
            "uniqueName": "banco-porcentajePromocion",  // Usando nombre único
            "value": banco.porcentaje_promocion.toString()
        },
        {
            "uniqueName": "banco-fechaPromocion",  // Usando nombre único
            "value": banco.fecha_promocion
        }
    ]
})



Tipos de campos soportados y su sintaxis para MongoDB y Función:

Para que la precarga de datos funcione correctamente en eventos de tipo MongoDB y Función JavaScript, cada tipo de evento debe retornar los datos en el formato adecuado según el tipo de campo. A continuación se detalla la estructura de respuesta para cada tipo de campo:

Tipo de CampoEstructura de RespuestaValor
TextoEl valor es de tipo string, es decir, un texto simple."Juan Pérez"
PorcentajeEl valor es un número entero, pero se debe almacenar como string."75"
GrillaLa estructura es un arreglo de arreglos, donde cada sub-arreglo tiene un número seguido de un texto.[[1, "Item A"], [2, "Item B"]]
PromptLa estructura es un objeto que tiene una propiedad value de tipo number y una propiedad description que es un arreglo de objetos con label (string) y value (puede ser string, boolean o number).{ "value": 3, "description": [{ "label": "Categoría", "value": "Evento" }] }
Archivo adjuntoLa estructura es un arreglo de objetos, donde cada objeto tiene las propiedades uuid, name, type y size (todas son requeridas).[ { "uuid": "id-unico", "name": "documento.docx", "type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "size": 45678 } ]
Texto largoEl valor es de tipo string, pero se permite incluir saltos de línea."Descripción línea 1\nDescripción línea 2"
FechaEl valor es un string en formato ISO 8601, que tiene la forma "YYYY-MM-DDTHH:MM:SS.sssZ"."2024-04-08T00:00:00.000Z"
NúmeroEl valor es de tipo number, y debe ser un número entero o decimal. Esto se valida verificando que typeof value === "number". Esto asegura que solo los valores numéricos sean aceptados.42
ComboEl valor es un objeto con la propiedad value, que puede ser de tipo number o string. La estructura es: module.exports = { type: "object", properties: { value: { type: ["number", "string"] } }, required: ["value"] };{ "value": "Opción 1" }
Combo múltipleEl valor es un arreglo de objetos, donde cada objeto tiene las propiedades value y label, ambas de tipo string.[ { "value": "Opción 1", "label": "Etiqueta 1" }, { "value": "Opción 2", "label": "Etiqueta 2" } ]
BooleanoEl valor es de tipo boolean, es decir, true o false.true o false



Estructura de ejemplo para cada tipo de campo

Para un formulario que contiene cada tipo de campo, la estructura correcta para precargar los datos de cada campo sería la siguiente. Se puede usar O id O uniqueName para identificar el campo:

[
  {
    "id": "21", // Porcentaje - Usando ID numérico
    "value": "98"
  },
  {
    "uniqueName": "usuario-nombre", // Texto - Usando nombre único
    "value": "Juan Pérez"
  },
  {
    "id": "25", // Grilla - Usando ID numérico
    "value": [
      [1, "Item A"],
      [2, "Item B"]
    ]
  },
  {
    "uniqueName": "usuario-evento", // Prompt - Usando nombre único
    "value": {
      "value": 2,
      "description": [
        {
          "label": "id",
          "value": 2
        },
        {
          "label": "Nombre",
          "value": "Hackathon Tecnológico"
        },
        {
          "label": "Es presencial",
          "value": "No"
        }
      ]
    }
  },
  {
    "id": "28", // Archivo adjunto - Usando ID numérico
    "value": [
      {
        "uuid": "123e4567-e89b-12d3-a456-426614174000",
        "name": "documento.pdf",
        "type": "application/pdf",
        "size": 102400
      }
    ]
  },
  {
    "uniqueName": "usuario-descripcion", // Texto largo - Usando nombre único
    "value": "Descripción línea 1\nDescripción línea 2"
  },
  {
    "id": "31", // Fecha - Usando ID numérico
    "value": "2023-05-15T10:30:00.000Z"
  },
  {
    "uniqueName": "usuario-cantidad", // Número - Usando nombre único
    "value": 100
  },
  {
    "id": "37", // Combo - Usando ID numérico
    "value": {
      "value": "primaria",
      "label": "Primaria"
    }
  },
  {
    "uniqueName": "usuario-equipos", // Combo múltiple - Usando nombre único
    "value": [
      {
        "value": "laptop",
        "label": "Laptop Dell"
      },
      {
        "value": "monitor",
        "label": "Monitor 24 pulgadas"
      }
    ]
  },
  {
    "id": "42", // Booleano - Usando ID numérico
    "value": true
  }
]