Guía de resolución de problemas de Jutro

En esta guía se resumen problemas comunes informados para Jutro Web Apps y herramientas relacionadas, agrupados en áreas problemáticas clave. Está diseñado para clientes externos como primera línea de soporte y para complementar la documentación del producto Jutro.

Cómo usar esta guía

• Comience desde la sección que coincida con su problema (actualizaciones, configuración del entorno, compilación e implementación, autenticación, paquetes compartidos o interfaz de usuario/pruebas).
• Aplique los pasos en problema → causa → solución para su situación.
• Si el problema continúa después de seguir las instrucciones, recopile registros, detalles de configuración e información del entorno y, luego, comuníquese con Asistencia Técnica de Guidewire. Cuando describa el problema, haga referencia al título de la situación en esta guía para que el Asistencia Técnica pueda indicarle rápidamente cuál es la documentación pertinente.

Actualizaciones de software y de versión de la aplicación de Jutro

Se produjo un error de paquete no disponible durante la instalación de los paquetes @jutro o @digitalsdk

Problema:
Al usar npm para instalar paquetes @jutro o @digitalsdk, aparece un error que indica que los paquetes no están disponibles.

Causa:
Los ámbitos para los paquetes @jutro y @digitalsdk no están configurados en su entorno local.

Solución:

1. Verifique que los ámbitos @jutro y @digitalsdk no estén configurados.
   • En el terminal raíz del proyecto, ejecute npm config get @jutro:registry y npm config get @digitalsdk:registry.
   • Si el ámbito no está configurado, el comando devuelve undefined. De lo contrario, el comando devuelve la URL de Artifactory.
2. Siga los pasos de configuración del entorno de desarrollo local para configurar los ámbitos.
   • Consulte Configuración de su entorno de desarrollo local para conocer los pasos necesarios.

La actualización de la aplicación no aparece en el entorno de destino

Problema:
Después de actualizar una aplicación y desencadenar una actualización, los cambios no aparecen en el entorno de destino.

Causa:
Se completó la canalización de actualización para el entorno de origen o el SDK, pero el paso correspondiente de ascenso o implementación inmutable no se ejecutó o falló. En algunos casos, la aplicación ya se encuentra en la última implementación que se puede ascender para ese entorno, o bien, las reglas de ascenso (como las que determinan que solo las implementaciones inmutables son aptas) no se cumplen.

Solución:

1. Verifique cuál es la implementación más reciente en el entorno de origen.
   • En la interfaz de usuario de Jutro Web Apps, verifique las vistas Actualizaciones de la aplicación, Ascensos de la aplicación o Implementaciones inmutables y verifique que la última compilación se haya completado correctamente en el entorno de origen.
2. Verifique si se cumplen los criterios para el ascenso.
   • Asegúrese de que la implementación que desea ascender sea inmutable (si así lo exige su modelo de ascenso) y de que los límites o reglas de ascenso (por ejemplo, un número máximo de implementaciones activas) no bloqueen el ascenso.
3. Volver a ejecutar el ascenso.
   • Vuelva a desencadenar manualmente el ascenso desde la consola o desde su canalización de CI/CD y preste atención a los errores (por ejemplo, problemas de permisos, límites de cuota o falta de configuración).
4. Si el ascenso sigue fallando, registre los identificadores de implementación y ascenso y póngase en contacto con Asistencia Técnica de Guidewire para que se investiguen las restricciones específicas del entorno.

Para obtener más información, consulte Actualizaciones de la aplicación.

La regeneración del SDK de Digital se realiza correctamente, pero la aplicación generada no se ejecuta

Problema:
Usted regenera el SDK de Digital o actualiza una aplicación basada en plantillas, pero después de extraer el código generado y ejecutar npm start o npm run build, la aplicación no se inicia o arroja errores de tiempo de ejecución.

Causa:
La versión regenerada del SDK de Digital y las dependencias del proyecto local no están sincronizadas. Los problemas comunes incluyen los siguientes:

• Se actualizó el SDK de Digital, pero el package.json local no se correspondía con las versiones de dependencia requeridas.
• Los cambios personalizados en la aplicación entran en conflicto con el código de la aplicación actualizado.
• La versión del Node.js local no coincide con la versión esperada por el SDK de Digital (por ejemplo, después de una migración de versión del nodo).

Solución:

1. Haga coincidir las versiones de dependencia.
   • Compare el package.json del proyecto generado con las dependencias de su aplicación y actualice las versiones para que coincidan.
2. Verifique la versión de Node.js.
   • Controle que esté utilizando la versión de Node.js especificada en la documentación de Jutro o en las notas de la versión del SDK de Digital para la versión de Jutro que tiene como destino.
3. Circunscriba las personalizaciones.
   • Revierta temporalmente o comente el código personalizado agregado por encima de la aplicación. Verifique que la aplicación base se ejecuta con el nuevo SDK de Digital y, a continuación, vuelva a aplicar las personalizaciones una a la vez hasta que identifique el conflicto.
4. Vuelva a ejecutar la generación del SDK de Digital con cuidado.
   • Repita los pasos de regeneración del SDK de Digital y asegúrese de que todas las variables de entorno y las credenciales requeridas para la generación estén configuradas correctamente y de que esté utilizando los comandos recomendados.

Para obtener más información, consulte Compilación e implementación de Jutro Web Apps.

Configuración inicial de Jutro Web Apps y configuración del entorno

El mosaico de Jutro Web Apps no está visible

Problema:
Espera ver un mosaico de Jutro Web Apps (o un mosaico específico de aplicación de Jutro) en su portal Guidewire Home, pero el mosaico no aparece para algunos usuarios o entornos.

Causa:
El usuario no pertenece a los grupos de autorización correctos requeridos para la visibilidad de los mosaicos o los patrones de grupo se han configurado con nombres solo internos u obsoletos. Como resultado, no se cumplen las condiciones de acceso que controlan la visibilidad de los mosaicos.

Solución:

1. Verifique los grupos requeridos para la aplicación.
   • Controle la configuración de los grupos de usuarios de autenticación (o equivalente) de la aplicación para ver qué patrones de grupo son necesarios para el acceso y la visibilidad.
2. Utilice patrones de grupo orientados al cliente.
   • Utilice los nombres de grupo y los patrones documentados para la configuración de Jutro Web Apps. Evite utilizar nombres heredados que puedan aparecer en ejemplos antiguos.
3. Verifique que la configuración sea la específica del entorno.
   • Asegúrese de que los grupos se creen en el entorno correcto (por ejemplo, prueba, preproducción o producción) y de que el usuario esté asignado a ellos en ese mismo entorno.
4. Vuelva a comprobar el acceso después de los cambios.
   • Pida al usuario que cierre sesión y vuelva a iniciarla, y luego verifique si aparece el mosaico. Si aún no aparece, registre las pertenencias a grupos del usuario y los detalles del entorno antes de ponerse en contacto con Asistencia Técnica de Guidewire.

Para obtener más información, consulte Acceso a Jutro Web Apps y Grupos de usuarios de autenticación.

Compilación e implementación (incluyendo CI/CD)

Se produce un error en el script npm start para las aplicaciones de inicio o de muestra

Problema:
Mientras sigue una ruta de aprendizaje de Jutro o un tutorial de la aplicación de inicio, la ejecución de npm start (o un script equivalente, como npm run build) falla con errores de script, dependencia o compilación.

Causa:

• El tutorial o la documentación de inicio dan por sentado que hay un script (npm start o similar) que ya no coincide con el package.json actual.
• El proyecto se está iniciando con una herramienta diferente (por ejemplo, npx en lugar del comando documentado) o las dependencias han cambiado desde que se escribió el tutorial.

Solución:

1. Revise los scripts de package.json.
   • Abra package.json y verifique qué scripts están definidos (por ejemplo, dev, start o serve). Utilice el nombre del script que esté realmente definido.
2. Siga las instrucciones del tutorial más recientes.
   • Utilice la versión más reciente de los tutoriales y las guías de inicio rápido de Jutro, y prefiera los comandos documentados allí sobre los ejemplos más antiguos.
3. Lleve a cabo una instalación limpia de las dependencias.
   • Elimine node_modules y su archivo de bloqueo, luego ejecute una instalación limpia (npm ci o npm install) usando la versión de Node.js especificada para su versión de SDK de Jutro.
4. Si los errores persisten, registre el comando completo, la versión del Node.js y el resultado del error antes de ponerse en contacto con Asistencia Técnica de Guidewire.

Para obtener más información, consulte Compilación e implementación de Jutro Web Apps.

La compilación de CI (por ejemplo, TeamCity) falla o se comporta de manera diferente de las compilaciones locales

Problema:
La aplicación se compila o ejecuta correctamente de manera local, pero su sistema de CI (por ejemplo, TeamCity) falla con errores de compilación o se comporta de manera diferente (por ejemplo, las pruebas fallan solo en CI o las compilaciones basadas en Docker se comportan de manera inesperada).

Causa:

• CI utiliza una versión de Node.js, una imagen de Docker o variables de entorno diferentes a las de su entorno local.
• Los problemas de compilación e instalación específicos de Windows surgen cuando se usan imágenes o herramientas de Docker probadas principalmente en Linux o macOS.

Solución:

1. Compare las versiones de Node.js y de la cadena de herramientas.
   • Verifique que la versión de Node.js, el administrador de paquetes y las herramientas de compilación de Jutro en CI coincidan con las versiones documentadas para Jutro y utilizadas localmente.
2. Revise que la configuración de CI sea la indicada en la documentación.
   • Haga que los pasos de la canalización de CI coincidan con la documentación sobre compilación e implementación, incluidas las variables de entorno necesarias, las etapas de compilación y la configuración de almacenamiento en caché.
3. Consulte las notas específicas de la plataforma.
   • Si compila en Windows o usa imágenes de Docker basadas en Windows, revise las notas específicas de la plataforma en la documentación y ajuste la canalización en consecuencia.
4. Recopile registros detallados.
   • Habilite el registro detallado en su compilación de CI y revise el resultado para detectar diferencias con su compilación local.

Para obtener más información, consulte Compilación e implementación de Jutro Web Apps.

El ascenso falla debido a reglas o límites de implementación inmutables

Problema:
Intentar ascender una implementación a un entorno superior falla en la interfaz de usuario de Jutro Web Apps, aunque la implementación parezca estar en buen estado.

Causa:
La implementación no cumple con los requisitos según el modelo de implementaciones inmutables o existen restricciones, como el máximo de implementaciones activas o tipos de implementación que no se corresponden.

Solución:

1. Controle el tipo de implementación.
   • En la vista Implementaciones inmutables, verifique que la implementación esté marcada como inmutable y que se pueda ascender al entorno deseado.
2. Controle los límites de implementación activos.
   • Revise si el entorno de destino ha alcanzado su límite configurado para implementaciones activas. Elimine o archive implementaciones antiguas que no se utilicen, si fuera necesario.
3. Vuelva a desencadenar el ascenso.
   • Después de ajustar la configuración o los límites, intente el ascenso otra vez y verifique que se complete correctamente.

Para obtener más información, consulte Implementaciones inmutables y Ascenso de aplicaciones.

Autenticación y autorización

El usuario no puede iniciar sesión después de cambios en la configuración de Okta o Guidewire Hub

Problema:
Después de actualizar la configuración de autenticación, los usuarios no pueden iniciar sesión, son redirigidos una y otra vez o ven errores relacionados con tokens.

Causa:
La configuración de autenticación no es coherente en la configuración de la aplicación, el inquilino de Okta y Guidewire Hub. Los problemas comunes incluyen URI de redirección incorrectos, valores del emisor, ID de cliente o ámbitos no coincidentes.

Solución:

1. Verifique los URI de redirección y la configuración del emisor.
   • Controle que el URI de redirección configurado en su aplicación coincida exactamente con el URI configurado en Okta y cualquier configuración de Guidewire Hub relacionada.
2. Controle el ID y los ámbitos del cliente.
   • Asegúrese de que el ID del cliente, la audiencia y los ámbitos solicitados coincidan con el registro de la aplicación y la configuración documentada.
3. Revise la orientación de configuración más reciente.
   • Utilice la documentación más reciente sobre configuración inicial de su aplicación con Okta o Guidewire Hub, no contenido anterior que use términos o flujos obsoletos.
4. Reúna tokens y registros si fuera necesario.
   • Si los problemas continúan, registre los tokens de ID y acceso (con valores confidenciales censurados) y los registros de aplicaciones y de Okta relevantes antes de comunicarse con Asistencia Técnica de Guidewire.

Para obtener más información, consulte Configuración de mi aplicación con Okta.

Uso de @jutro/auth sin herramientas de compilación de Jutro (por ejemplo, Vite o React)

Problema:
Desea usar la autenticación de Jutro (@jutro/auth) en una aplicación de React creada con Vite u otra cadena de herramientas y la autenticación falla o se comporta de manera incoherente.

Causa:
@jutro/auth prevé variables de entorno específicas, archivos de configuración y un patrón de integración AuthProvider que normalmente proporcionan las herramientas de compilación de Jutro. Cuando se utiliza fuera de la cadena de herramientas de Jutro, esas expectativas no se cumplen automáticamente.

Solución:

1. Siga el patrón de integración AuthProvider documentado.
   • Asegúrese de que su aplicación de React personalizada encapsule su árbol de componentes en el AuthProvider de Jutro previsto y pase todas las opciones de configuración necesarias (por ejemplo, emisor, ID de cliente y URI de redireccionamiento).
2. Cree un reflejo de las variables de entorno de Jutro.
   • Establezca las mismas variables de entorno (por ejemplo, terminales de autenticación, audiencia, ámbitos) utilizadas por una aplicación generada por Jutro, siguiendo los patrones que se muestran en la documentación.
3. Haga coincidir el tiempo de compilación con la configuración de tiempo de ejecución.
   • Controle que la configuración de compilación (por ejemplo, configuración de Vite) exponga correctamente las variables relacionadas con autenticación en el momento de la compilación y que están disponibles en el tiempo de ejecución en el navegador.

Para obtener más información, consulte Configuración de mi aplicación con Okta.

Paquetes compartidos, Artifactory y cambios en la versión del nodo

La nueva versión del paquete compartido no se resuelve

Problema:
Después de publicar una nueva versión de un paquete compartido en Artifactory, los consumidores continúan resolviendo una versión anterior o ven errores del tipo “versión no encontrada” durante la instalación.

Causa:

• Las cachés de Artifactory o intermediarias necesitan tiempo para actualizarse, especialmente para los paquetes recién publicados o migrados.
• La aplicación consumidora está anclada a una versión anterior (o usa un intervalo que no incluye la nueva versión).
• La aplicación no usa el grupo de repositorio binario correcto (por ejemplo, usa un grupo de desarrolladores, en lugar del grupo de lectura documentado).

Solución:

1. Permita retardos en el almacenamiento en caché.
   • Espere un momento y vuelva a intentar instalar el paquete, ya que el almacenamiento en caché puede retrasar la visibilidad de las nuevas versiones.
2. Verifique los intervalos de versión de dependencia.
   • Controle que la versión solicitada o el intervalo del versionado semántico de package.json incluyan la versión recién publicada.
3. Use el grupo de repositorio binario correcto.
   • Controle que el proyecto esté configurado para utilizar el grupo de Artifactory documentado (por ejemplo, un grupo {tenant}.all.all.all.binrepo.read), en lugar de grupos obsoletos o incorrectos.
4. Controle la publicación en Artifactory.
   • En la interfaz de usuario de Artifactory, verifique que aparezca la nueva versión y que la operación de publicación se haya completado correctamente.

Para obtener más información, consulte Paquetes compartidos.

Las compilaciones fallan durante o después de una migración de versión de nodo (por ejemplo, nodo 22)

Problema:
Las compilaciones que funcionaban antes ahora fallan después de una migración de versión de la plataforma Node.js, en especial cuando se consumen o publican paquetes compartidos.

Causa:

• El entorno local o CI no utiliza la versión de Node.js en correspondencia con la migración de la plataforma.
• Algunas dependencias o scripts de compilación se basan en un comportamiento que cambió en la versión más reciente de Node.js.

Solución:

1. Utilice la versión de Node.js recomendada.
   • Asegúrese de que tanto su entorno local como las canalizaciones de CI usen la versión de Node.js especificada en la documentación de Jutro o en las notas de la versión del SDK.
2. Actualice las dependencias incompatibles.
   • Controle las incompatibilidades conocidas con la nueva versión de Node.js y actualice los paquetes afectados.
3. Vuelva a ejecutar las compilaciones con cachés limpias.
   • Borre las cachés del administrador de paquetes y CI antes de volver a compilar para evitar el uso de artefactos compilados de la versión anterior de Node.js.

Para obtener más información, consulte Paquetes compartidos y Compilación e implementación de Jutro Web Apps.

Situaciones de prueba y de interfaz de usuario adicionales

El estilo de las entradas de divisa se invalida en el modo de solo visualización

Problema:
Al utilizar el componente CurrencyInput en el modo displayOnly, la aplicación de estilos personalizados con className al parecer no surte efecto; los estilos proporcionados por Jutro los invalidan.

Causa:
El estilo interno del componente tiene una mayor especificidad que el proporcionado por el usuario className, por ello, sus estilos no ganan en la cascada CSS.

Solución:

1. Utilice selectores más específicos o invalidaciones de estilo.
   • Aplique estilos con selectores que apunten al elemento interno (por ejemplo, agregue una clase encapsuladora y use selectores anidados), o bien, use un mecanismo de tematización recomendado para los componentes de Jutro.
2. Prefiera las API de temas documentadas.
   • Cuando estén disponibles, utilice las API de invalidación de tema o estilo descritas en la documentación del componente, en lugar de depender únicamente de className.

Para obtener más información, consulte la documentación sobre los componentes de Jutro en Referencia de la interfaz de usuario de Jutro.

La propiedad to del componente enlace de Jutro no funciona como estaba previsto

Problema:
La propiedad to del componente enlace no navega como estaba previsto o se resuelve en una ruta incorrecta.

Causa:
La configuración de enrutamiento de la aplicación no coincide con las expectativas del componente enlace de Jutro (por ejemplo, falta contexto de enrutador, ruta base incorrecta o discrepancia entre rutas relativas y absolutas).

Solución:

1. Controle la configuración del enrutador.
   • Asegúrese de que la aplicación esté encapsulada en el proveedor de enrutador previsto y de que la ruta base esté configurada de forma coherente con las rutas utilizadas por el enlace.
2. Pruebe la ruta de forma aislada.
   • Navegue directamente a la URL de destino en el navegador para verificar que sea válida y que la información se entregue correctamente.
3. Siga los ejemplos de enrutamiento.
   • Compare su uso del componente enlace con ejemplos de enrutamiento en la documentación de Jutro y ajuste su configuración en consecuencia.

Para obtener más información, consulte la documentación sobre los componentes de Jutro en Referencia de la interfaz de usuario de Jutro.

El comportamiento de las pruebas difiere según la zona horaria

Problema:
Las pruebas unitarias que involucran el comportamiento de fecha u hora fallan cuando se ejecutan en diferentes zonas horarias, aunque la lógica de la aplicación no haya cambiado.

Causa:
Las pruebas se basan en la zona horaria del sistema local, en lugar de una zona horaria de prueba fija y explícita. Esto conduce a diferentes expectativas para el formato o los cálculos de fecha y hora en los entornos.

Solución:

1. Estandarice la zona horaria de la prueba.
   • Configure el ejecutor de pruebas para que utilice una zona horaria fija (por ejemplo, UTC) y escriba aserciones que supongan esa zona horaria.
2. Evite los horarios locales con códigos rígidos.
   • Utilice el manejo explícito de fechas que tengan en cuenta la zona horaria en las pruebas y el código de aplicación, y normalice las horas en una referencia coherente al comparar valores.

Para obtener más información, consulte la documentación sobre pruebas y prácticas recomendadas de Jutro en la orientación para desarrolladores de Jutro.

Guía de gestión de estado para aplicaciones de Jutro

Problema:
No está seguro de cuál sea la mejor manera de gestionar formularios complejos o el estado de la aplicación en las aplicaciones de Jutro, y si debe confiar en los patrones de Jutro, las bibliotecas de gestión de estado externas o una combinación de ambos.

Causa:
Jutro admite varios patrones para administrar el estado y el mejor enfoque depende de la complejidad de su aplicación. Sin orientación, los equipos pueden combinar patrones o usar bibliotecas externas de maneras que entren en conflicto con el enlace y la validación de datos de Jutro.

Solución:

1. Comience con los patrones documentados de Jutro.
   • Prefiera los patrones de manejo integrados de formularios y estado descritos en la documentación de Jutro para situaciones comunes de CRUD y flujo de trabajo.
2. Utilice bibliotecas externas cuando se justifique.
   • Para aplicaciones más grandes o muy interactivas, puede usar bibliotecas externas de gestión de estado, siempre que:
     • mantenga el manejo de datos sensibles según las recomendaciones de Jutro;
     • no omita el enlace de datos de Jutro de maneras que interfieran con la validación o el control de acceso.
3. Documente internamente el patrón elegido.
   • Registre y comparta el enfoque de gestión de estado acordado dentro de su equipo para que se aplique de manera coherente en todas las aplicaciones.

Resolución de problemas del SDK de Digital

Las solicitudes se envían sin encabezados de ubicación o con los incorrectos

Problema:
Las solicitudes salientes a ClaimCenter, BillingCenter o PolicyCenter se envían sin encabezados de ubicación o con los incorrectos.

Causa:
Los encabezados que pasan información de localización no se agregan automáticamente a las solicitudes del SDK de Digital. Debe agregar un código que actualice la configuración para incluir estos datos en las solicitudes.

Note: Esta es una solución temporal hasta que el problema se resuelva en una versión futura. Cuando se resuelva el problema, el interceptor se agregará automáticamente y podrá eliminar el código de solución temporal.

Solución:

Para agregar el interceptor de localización, realice los siguientes cambios durante la etapa de inicialización de la configuración de su SDK de Digital:

1. Inicialice cada SDK que utilice (ClaimCenter, BillingCenter o PolicyCenter).
2. Inmediatamente después de cada llamada de inicialización, registre un interceptor de solicitudes en el restService de ese SDK.
3. En el interceptor, agregue los encabezados GW-Language y GW-Locale de su idioma y valores de configuración regional actuales.

El siguiente bloque de código muestra un ejemplo para ClaimCenter:

import { useLanguage, useLocale } from '@jutro/locale';
import {
  initSdk as initCCSdk,
  getSdkConfig as getCcSdkConfig,
} from '../generated/CcSdk';

const localeContext = useLocale();
const languageContext = useLanguage();
const currentLanguage = languageContext.language;
const currentLocale = localeContext.locale;

initCCSdk({
  auth: {<your-auth-details>},
});
getCcSdkConfig().restService.axiosInterceptors.request.use((config) => ({
  ...config,
  headers: {
    ...config.headers,
    'GW-Language': currentLanguage,
    'GW-Locale': currentLocale,
  },
}));