Lectura: 3 minutos

Oracle APEX expone un namespace apex.util con decenas de funciones de utilidad. La documentación oficial cubre las más conocidas, pero hay algunas que viven en la sombra y resultan muy prácticas en el día a día. En este post te muestro 3 de ellas con ejemplos reales: getContextString, getTopApex y getDateFromISO8601String.

---

1. apex.util.getContextString() — contexto de la sesión actual

¿Qué hace?

Devuelve un string con información del contexto actual de la aplicación: el nombre de la app, la página activa y el ID de sesión. Es especialmente útil para enriquecer mensajes de error o logs enviados a un proceso del servidor.

Sintaxis

js

apex.util.getContextString()
//'p_context=aprendiz-academy/home/3509377707687'

Ejemplo 1 — log de errores enriquecido

Sin getContextString tus logs dicen “algo falló”. Con él, dicen exactamente en qué app, página y sesión.

js

try {
  // operación que puede fallar
  const datos = JSON.parse(apex.items.P1_JSON_DATA.value);
  procesarDatos(datos);
} catch (e) {
  const ctx = apex.util.getContextString();
  console.error(`[ERROR] Contexto: ${ctx}`, e.message);
  // → [ERROR] Contexto: p_context=portalweb-apex/registro/8523419
}

Ejemplo 2 — reporte de error a un proceso APEX

js

function reportarError(mensaje) {
  apex.server.process("LOG_CLIENT_ERROR", {
    x01: apex.util.getContextString(), // contexto completo
    x02: mensaje,
    x03: navigator.userAgent
  }, {
    success: function() {
      apex.message.showPageSuccess("Error registrado. El equipo fue notificado.");
    }
  });
}

Ejemplo 3 — alerta de depuración en desarrollo

js

// Solo activa en modo debug
if (apex.env.APP_DEBUG === "YES") {
  apex.message.alert(
    "Contexto actual:<br><code>" + apex.util.getContextString() + "</code>"
  );
}

---

2. apex.util.getTopApex() — acceder al apex de la página padre desde un modal

¿Qué hace?

Cuando una página se abre como Dialog Region (modal), el objeto apex disponible dentro de ese frame apunta al contexto del modal, no al de la página que lo abrió. getTopApex() regresa el objeto apex del frame padre, lo que te permite leer ítems, refrescar regiones o cerrar el modal desde adentro.

Sintaxis

js

const parentApex = apex.util.getTopApex();
parentApex.items.P1_USUARIO.value; // lee ítem de la página padre

Ejemplo 1 — leer un ítem de la página padre

js

// Dentro de una Dynamic Action en la página modal

// ❌ Esto puede fallar si P1_USUARIO no existe en el modal
const usuario = apex.items.P1_USUARIO.value;

// ✅ Esto siempre apunta a la página que abrió el modal
const parentApex = apex.util.getTopApex();
const usuario = parentApex.items.P1_USUARIO.value;

apex.items.P2_CREADO_POR.value = usuario; // asigna en el modal

Ejemplo 2 — refrescar una región del padre al cerrar el modal

Patrón clásico: el usuario guarda un registro en el modal y al cerrarlo el Interactive Grid del padre debe actualizarse.

js

// En el botón "Guardar" del modal — después de apex.server.process(...)
function guardarYCerrar() {
  apex.server.process("GUARDAR_EMPLEADO", {
    x01: apex.items.P2_NOMBRE.value,
    x02: apex.items.P2_RFC.value
  }, {
    success: function() {
      const parentApex = apex.util.getTopApex();

      // Refresca el IG en la página padre
      parentApex.region.findOne("ig-reporte").refresh();

      // Cierra el modal
      parentApex.navigation.dialog.close(true);
    }
  });
}

Ejemplo 3 — pasar un valor del modal a la página padre sin cerrar

Útil para lookups: el usuario selecciona un registro en el modal y el valor se refleja en la página padre en tiempo real.

js

// Al hacer clic en una fila del IR dentro del modal
$(document).on("click", "#mi-reporte .t-Report-cell[headers='COL_ID']", function() {
  const idSeleccionado = $(this).text().trim();
  const parentApex = apex.util.getTopApex();

  // Asigna el valor en la página padre
  parentApex.items.P1_EMPLEADO_ID.value = idSeleccionado;

  // Dispara un DA en la página padre (si tiene evento "Change")
  parentApex.event.trigger(
    parentApex.items.P1_EMPLEADO_ID.node,
    "change"
  );

  // Cierra el modal
  parentApex.navigation.dialog.close(true);
});

---

3. apex.util.getDateFromISO8601String() — parsear fechas ISO de forma segura

¿Qué hace?

Convierte un string en formato ISO 8601 a un objeto Date de JavaScript. Es más robusto que new Date(str) porque new Date() tiene comportamiento inconsistente entre navegadores con ciertos formatos de fecha (especialmente los que no incluyen hora).

Sintaxis

js

const fecha = apex.util.getDateFromISO8601String("2025-03-15T14:30:00Z");
// → Date object

Ejemplo 1 — calcular días transcurridos desde una fecha de un ítem

js

const isoStr = apex.items.P1_FECHA_PEDIDO.value;
// El valor de un ítem de tipo Date en APEX llega como ISO string desde el servidor

const fechaPedido = apex.util.getDateFromISO8601String(isoStr);
const hoy = new Date();
const diasTranscurridos = Math.floor((hoy - fechaPedido) / 86400000);

if (diasTranscurridos > 30) {
  apex.message.showErrors([{
    type: "error",
    location: "page",
    message: `Este pedido tiene ${diasTranscurridos} días sin atender.`
  }]);
}

Ejemplo 2 — validar que fecha de fin sea mayor que fecha de inicio

js

function validarRangoFechas() {
  const inicio = apex.util.getDateFromISO8601String(apex.items.P1_FECHA_INICIO.value);
  const fin    = apex.util.getDateFromISO8601String(apex.items.P1_FECHA_FIN.value);

  if (fin <= inicio) {
    apex.message.showErrors([{
      type:     "error",
      location: ["page", "inline"],
      pageItem: "P1_FECHA_FIN",
      message:  "La fecha de fin debe ser posterior a la fecha de inicio."
    }]);
    return false;
  }
  return true;
}

Ejemplo 3 — mostrar un countdown en la página

js

const fechaVencimiento = apex.util.getDateFromISO8601String(
  apex.items.P1_FECHA_VENCIMIENTO.value
);

function actualizarCountdown() {
  const ahora = new Date();
  const diff  = fechaVencimiento - ahora;

  if (diff <= 0) {
    $("#countdown").text("Vencido").addClass("u-danger-text");
    return;
  }

  const dias  = Math.floor(diff / 86400000);
  const horas = Math.floor((diff % 86400000) / 3600000);
  $("#countdown").text(`Vence en ${dias}d ${horas}h`);
}

actualizarCountdown();
setInterval(actualizarCountdown, 60000);

---

Resumen

Función	Cuándo usarla
apex.util.getContextString()	Logs de errores, reporte de bugs con contexto de sesión
apex.util.getTopApex()	Cualquier código dentro de un Dialog Region que necesite interactuar con la página padre
apex.util.getDateFromISO8601String()	Validaciones de fechas, cálculos de días, countdowns

Las tres están disponibles sin necesidad de importar nada extra — son parte del objeto apex que ya carga en cualquier aplicación APEX.

---

¿Conoces otras funciones no documentadas de apex.util? Déjalo en los comentarios.

Referencias

https://docs.oracle.com/en/database/oracle/apex/24.2/aexjs/apex.util.html