Guide de dépannage Jutro

Ce guide récapitule les problèmes courants signalés pour Jutro Web Apps et les outils associés, regroupés par domaines problématiques clés. Il est destiné aux clients externes en tant que première ligne de support et en complément de la documentation produit Jutro.

Comment utiliser ce guide

• Commencez par la section qui correspond à votre problème (mises à jour, configuration de l’environnement, build et déploiement, authentification, packages partagés ou interface utilisateur/tests).
• Appliquez les étapes Problème → Cause → Solution à votre scénario.
• Si le problème persiste après avoir suivi les instructions, collectez les journaux, les détails de la configuration et les informations sur l’environnement, puis contactez l'assistance Guidewire. Reportez-vous au titre du scénario de ce guide lorsque vous décrivez le problème afin que l’assistance puisse rapidement se reporter à la documentation pertinente.

Mises à jour et mises à niveau de l’application Jutro

Erreur de package non disponible lors de l’installation des packages @jutro ou @digitalsdk

Problème :
Lorsque vous utilisez npm pour installer des packages @jutro ou @digitalsdk, vous obtenez un message d’erreur indiquant que les packages ne sont pas disponibles.

Cause :
Vos champs d'application pour les packages @jutro et @digitalsdk ne sont pas définis dans votre environnement local.

Solution :

1. Vérifiez que les champs d'application @jutro et @digitalsdk ne sont pas configurés.
   • Dans le terminal racine de votre projet, exécutez npm config get @jutro:registry et npm config get @digitalsdk:registry.
   • Si le champ d'application n’est pas configuré, la commande renvoie undefined. Sinon, la commande renvoie votre URL Artifactory.
2. Suivez les étapes de configuration de l’environnement de développement local pour configurer les champs d'application.
   • Pour connaître les étapes requises, reportez-vous à la section Configuration de votre environnement de développement local.

La mise à jour de l’application n’apparaît pas dans l’environnement cible

Problème :
Après la mise à jour d’une application et le déclenchement d’une mise à jour, les modifications n’apparaissent pas dans l’environnement cible.

Cause :
Le pipeline de mise à jour s’est terminé pour l’environnement source ou le SDK, mais l’étape de promotion ou de déploiement non modifiable correspondante n’a pas été exécutée ou a échoué. Dans certains cas, l’application est déjà au dernier déploiement promouvable pour cet environnement, ou les règles de promotion (par exemple, seuls les déploiements non modifiables sont éligibles) ne sont pas satisfaites.

Solution :

1. Confirmez le dernier déploiement dans l’environnement source.
   • Dans l’interface utilisateur de Jutro Web Apps, vérifiez les vues Mises à jour de l’application, Promotions d’applications ou Déploiements non modifiables et assurez-vous que le dernier build s’est terminé correctement dans l’environnement source.
2. Vérifiez l’éligibilité à la promotion.
   • Assurez-vous que le déploiement que vous souhaitez promouvoir est non modifiable (si votre modèle de promotion l’exige) et que les limites ou règles de promotion (par exemple, un nombre maximal de déploiements actifs) ne bloquent pas la promotion.
3. Relancez la promotion.
   • Déclenchez à nouveau manuellement la promotion à partir de la console ou de votre pipeline CI/CD et surveillez les erreurs (par exemple, problèmes d’autorisation, limites de quota ou configuration manquante).
4. Si la promotion échoue toujours, notez les identifiants de déploiement et de promotion et contactez l'assistance Guidewire afin que les contraintes spécifiques à l’environnement puissent être étudiées.

Pour en savoir plus, consultez la section Mises à jour de l’application

La régénération du SDK Digital a réussi, mais l’application générée n’exécute pas

Problème :
Vous régénérez le SDK Digital ou mettez à jour une application basée sur un modèle, mais après l’extraction du code généré et l’exécution de npm start ou npm run build, l’application ne parvient pas à démarrer ou génère des erreurs d’exécution.

Cause :
La version régénérée du SDK Digital et les dépendances de projet locales ne sont pas synchronisées. Les problèmes les plus courants sont les suivants :

• Le SDK Digital a été mis à jour, mais le package.json local n’était pas aligné sur les versions de dépendance requises.
• Les modifications personnalisées apportées à l’application entrent en conflit avec le code de l’application mis à jour.
• La version du Node.js locale ne correspond pas à la version attendue par le SDK Digital (par exemple, après une migration de version Node).

Solution :

1. Alignez les versions de dépendance.
   • Comparez les package.json du projet généré avec les dépendances de votre application et mettez à jour les versions pour qu'elles correspondent.
2. Vérifiez la version Node.js.
   • Vérifiez que vous utilisez la version Node.js spécifiée dans la documentation Jutro ou dans les notes de version du SDK Digital pour la version Jutro que vous ciblez.
3. Isolez les personnalisations.
   • Supprimez ou commentez temporairement le code personnalisé ajouté au-dessus de l’application. Confirmez que l’application de base s’exécute avec le nouveau SDK Digital, puis réappliquez les personnalisations de manière incrémentielle jusqu’à ce que vous identifiiez le conflit.
4. Relancez la génération du SDK Digital avec précaution.
   • Répétez les étapes de régénération du SDK Digital, en vous assurant que toutes les variables d’environnement et les informations d’identification requises pour la génération sont correctement définies et que vous utilisez les commandes recommandées.

Pour en savoir plus, reportez-vous à Créer et déployer des applications Jutro Web Apps.

Configuration de Jutro Web Apps et configuration de l’environnement

La vignette Jutro Web Apps n’est pas visible

Problème :
Vous vous attendez à voir une vignette Jutro Web Apps (ou une vignette d’application Jutro spécifique) dans votre portail Guidewire Home, mais la vignette n’apparaît pas pour certains utilisateurs ou environnements.

Cause :
L’utilisateur n’appartient pas aux groupes d’autorisation appropriés requis pour la visibilité des vignettes, ou des modèles de groupe ont été configurés à l’aide de noms obsolètes ou réservés à un usage interne uniquement. Par conséquent, les conditions d’accès qui contrôlent la visibilité des vignettes ne sont pas remplies.

Solution :

1. Vérifiez les groupes requis pour l’application.
   • Vérifiez la configuration des groupes d’utilisateurs d’authentification (ou équivalent) de l’application pour voir quels modèles de groupe sont requis pour l’accès et la visibilité.
2. Utilisez des modèles de groupe orientés client.
   • Utilisez les noms de groupe et les modèles documentés pour la configuration de Jutro Web Apps. Évitez d’utiliser des noms hérités qui peuvent apparaître dans des exemples plus anciens.
3. Confirmez la configuration spécifique à l’environnement.
   • Assurez-vous que les groupes sont créés dans le bon environnement (par exemple, test, preprod ou prod) et que l’utilisateur leur est attribué dans ce même environnement.
4. Vérifiez à nouveau l’accès une fois les modifications effectuées.
   • Demandez à l’utilisateur de se déconnecter et de se reconnecter, puis vérifiez si la vignette s’affiche. Si la vignette ne s'affiche toujours pas, saisissez les appartenances à un groupe de l’utilisateur et les détails de l’environnement avant de contacter l’assistance Guidewire.

Pour en savoir plus, reportez-vous à Accès aux applications Jutro Web Apps et aux groupes d’utilisateurs d’authentification.

Création et déploiement (y compris CI/CD)

Le script de démarrage npm échoue pour les applications de démarrage ou les exemples d'applications

Problème :
Lors de la réalisation d’un parcours d’apprentissage Jutro ou d’un tutoriel d’application de démarrage, l’exécution de npm start (ou d’un script équivalent, tel que npm run build) échoue avec des erreurs de script, de dépendance ou de build manquants.

Cause :

• Le tutoriel ou la documentation du kit de démarrage suppose un script (npm start ou similaire) qui ne correspond plus à la version actuelle de package.json.
• Le projet est démarré avec un outil différent (par exemple, npx au lieu de la commande documentée), ou les dépendances ont changé depuis la rédaction du tutoriel.

Solution :

1. Vérifiez les scripts package.json.
   • Ouvrez package.json et confirmez les scripts définis (par exemple, dev, startou serve). Utilisez le nom de script réellement défini.
2. Suivez les dernières instructions du tutoriel.
   • Utilisez la version la plus récente des tutoriels et des guides de démarrage rapide Jutro, et préférez les commandes qui y sont documentées aux exemples plus anciens.
3. Installez les dépendances proprement.
   • Supprimez node_modules et votre fichier de verrouillage, puis exécutez une nouvelle installation (npm ci ou npm install) en utilisant la version Node.js spécifiée pour votre version du SDK Jutro.
4. Si les erreurs persistent, notez la commande complète, la version de Node.js et la sortie d’erreur avant de contacter l'assistance Guidewire.

Pour en savoir plus, reportez-vous à Créer et déployer des applications Jutro Web Apps.

Le build CI (par exemple, TeamCity) échoue ou se comporte différemment des builds locaux

Problème :
L’application se compile ou s’exécute correctement localement, mais votre système CI (par exemple, TeamCity) échoue avec des erreurs de build ou se comporte différemment (par exemple, les tests échouent uniquement dans CI ou les builds basés sur Docker se comportent de manière inattendue).

Cause :

• CI utilise une version Node.js, une image Docker ou des variables d’environnement différentes de celles de votre environnement local.
• Des problèmes de génération et d’installation spécifiques à Windows surviennent lors de l’utilisation d’images ou d’outils Docker principalement testés sur Linux ou macOS.

Solution :

1. Comparez les versions Node.js et de chaîne d’outils.
   • Vérifiez que la version Node.js, Package Manager et les outils de compilation Jutro dans CI correspondent aux versions documentées pour Jutro et utilisées localement.
2. Vérifiez la configuration CI dans la documentation.
   • Alignez les étapes du pipeline CI sur la documentation relative au build et au déploiement, y compris les variables d’environnement requises, les étapes de build et la configuration de la mise en cache.
3. Vérifiez les notes spécifiques à la plate-forme.
   • Si vous créez sous Windows ou utilisez des images Docker basées sur Windows, consultez les notes spécifiques à la plate-forme dans la documentation et ajustez votre pipeline en conséquence.
4. Collectez les journaux détaillés.
   • Activez la journalisation détaillée dans votre build CI et vérifiez la sortie pour voir les différences par rapport à votre build local.

Pour en savoir plus, reportez-vous à Créer et déployer des applications Jutro Web Apps.

La promotion échoue en raison de règles ou de limites de déploiement non modifiables

Problème :
Toute tentative de promotion d’un déploiement vers un environnement supérieur échoue dans l’interface utilisateur de Jutro Web Apps, même si le déploiement semble correct.

Cause :
Le déploiement n’est pas éligible dans le cadre du modèle de déploiements non modifiables, ou il existe des contraintes telles que le nombre maximal de déploiements actifs ou des types de déploiement mal alignés.

Solution :

1. Confirmez le type de déploiement.
   • Dans la vue Déploiements non modifiables, vérifiez que le déploiement est marqué comme non modifiable et qu’il peut être promu dans l’environnement souhaité.
2. Vérifiez les limites de déploiement actif.
   • Vérifiez si l’environnement cible a atteint sa limite configurée pour les déploiements actifs. Supprimez ou archivez les anciens déploiements inutilisés, si nécessaire.
3. Relancez la promotion.
   • Après avoir ajusté la configuration ou les limites, relancez la promotion et vérifiez qu’elle s’est terminée correctement.

Pour en savoir plus, consultez les sections Déploiements non modifiables et Promotions d’applications.

Authentification et autorisation

L’utilisateur ne peut pas se connecter après les modifications apportées à la configuration d’Okta/Guidewire Hub

Problème :
Après la mise à jour des paramètres d’authentification, les utilisateurs ne peuvent pas se connecter, sont redirigés à plusieurs reprises ou voient des erreurs liées aux jetons.

Cause :
La configuration de l’authentification n’est pas cohérente dans les paramètres de l’application, du locataire Okta et de Guidewire Hub. Les problèmes courants incluent des URI de redirection, des valeurs d’émetteur, des ID client incorrects ou des champs d'application incompatibles.

Solution :

1. Vérifiez les URI de redirection et les paramètres de l’émetteur.
   • Vérifiez que l’URI de redirection configuré dans votre application correspond exactement à l’URI configuré dans Okta et toute configuration Guidewire Hub associée.
2. Confirmez l’ID client et les champs d'application.
   • Assurez-vous que l’ID client, le public et les champs d'application demandés correspondent à l’enregistrement de l’application et à la configuration documentée.
3. Consultez les derniers conseils de configuration.
   • Utilisez la documentation la plus récente relative à la configuration de votre application avec Okta/Guidewire Hub, et non du contenu plus ancien qui utilise des termes ou des flux obsolètes.
4. Enregistrez les jetons et les journaux si nécessaire.
   • Si les problèmes persistent, enregistrez l’ID et les jetons d’accès (avec les valeurs sensibles expurgées) ainsi que les journaux d’application et Okta pertinents avant de contacter l’assistance Guidewire.

Pour en savoir plus, reportez-vous à la section Configuration de mon application avec Okta.

Utilisation de @jutro/auth sans outils de compilation Jutro (par exemple, Vite/React)

Problème :
Vous souhaitez utiliser l’authentification Jutro (@jutro/auth) dans une application React créée avec Vite ou une autre chaîne d’outils, et l’authentification échoue ou se comporte de manière incohérente.

Cause :
@jutro/auth attend des variables d’environnement spécifiques, des fichiers de configuration et un modèle d’intégration AuthProvider qui sont normalement fournis par les outils de compilation Jutro. Lors d'une utilisation en dehors de la chaîne d’outils Jutro, ces attentes ne sont pas automatiquement satisfaites.

Solution :

1. Suivez le modèle d’intégration AuthProvider documenté.
   • Assurez-vous que votre application React personnalisée encapsule son arborescence de composants dans le AuthProvider Jutro attendu et transmet toutes les options de configuration requises (par exemple, l’émetteur, l’ID client et l’URI de redirection).
2. Reflétez les variables d’environnement Jutro.
   • Définissez les mêmes variables d’environnement (par exemple, points de terminaison d’authentification, public, champs d'application) que celles utilisées par une application générée par Jutro, en suivant les modèles présentés dans la documentation.
3. Alignez la configuration au moment de la création et de l’exécution.
   • Vérifiez que votre configuration de build (par exemple, la configuration Vite) expose correctement les variables liées à l’authentification lors de la compilation et qu’elles sont disponibles au moment de l’exécution dans le navigateur.

Pour en savoir plus, reportez-vous à la section Configuration de mon application avec Okta.

Modifications de packages partagés, d'Artifactory et de version Node

La nouvelle version du package partagé n’est pas déterminée

Problème :
Après la publication d’une nouvelle version d’un package partagé sur Artifactory, les utilisateurs déterminent toujours une version antérieure ou voient des erreurs « version introuvable » lors de l’installation.

Cause :

• L’actualisation des caches Artifactory ou intermédiaires demande du temps, en particulier pour les packages récemment publiés ou migrés.
• L’application utilisatrice est épinglée à une version antérieure (ou utilise une plage qui n’inclut pas la nouvelle version).
• L’application n’utilise pas le groupe de référentiel binaire approprié (par exemple, elle utilise un groupe de développeurs au lieu du groupe de lecture documenté).

Solution :

1. Prévoyez des délais de mise en cache.
   • Patientez quelques instants et réessayez d’installer le package car la mise en cache peut retarder la visibilité des nouvelles versions.
2. Vérifiez les plages de versions de dépendance.
   • Vérifiez package.json pour vous assurer que la version ou la plage semver demandée inclut la version récemment publiée.
3. Utilisez le groupe binrepo approprié.
   • Vérifiez que votre projet est configuré pour utiliser le groupe Artifactory documenté (par exemple, un groupe {tenant}.all.all.all.binrepo.read) au lieu de groupes obsolètes ou incorrects.
4. Confirmez la publication dans Artifactory.
   • Dans votre interface utilisateur Artifactory, vérifiez que la nouvelle version s’affiche et que l’opération de publication s’est terminée correctement.

Pour en savoir plus, reportez-vous à la section Packages partagés.

Les builds échouent pendant ou après une migration de version Node (par exemple, Node 22)

Problème :
Les builds qui fonctionnaient auparavant échouent désormais après une migration de version Node.js de plate-forme, en particulier lors de l’utilisation ou de la publication de packages partagés.

Cause :

• L’environnement local ou CI n’utilise pas la version Node.js alignée sur la migration de la plate-forme.
• Certaines dépendances ou scripts de build reposent sur un comportement qui a changé dans la nouvelle version Node.js.

Solution :

1. Utilisez la version Node.js recommandée.
   • Assurez-vous que votre environnement local et vos pipelines CI utilisent la version Node.js spécifiée dans la documentation Jutro ou les notes de version du SDK.
2. Mettez à jour les dépendances incompatibles.
   • Vérifiez les incompatibilités connues avec la nouvelle version de Node.js et mettez à jour les packages concernés.
3. Réexécutez les builds avec des caches propres.
   • Effacez les caches de Package Manager et CI avant de procéder à la recompilation afin d’éviter d’utiliser les artefacts compilés de la version Node.js précédente.

Pour en savoir plus, consultez les sections Packages partagés et Créer et déployer des applications Jutro Web Apps.

Interface utilisateur et scénarios de test supplémentaires

Le style des entrées de devise est remplacé en mode affichage uniquement

Problème :
Lorsque vous utilisez le composant CurrencyInput en mode displayOnly, l’application de styles personnalisés à l’aide de className ne semble pas prendre effet. Les styles fournis par Jutro les remplacent.

Cause :
Le style interne du composant a une spécificité plus élevée que le style className fourni par l’utilisateur, de sorte que vos styles ne sont pas prioritaires dans la cascade CSS.

Solution :

1. Utilisez des sélecteurs ou des remplacements de style plus spécifiques.
   • Appliquez des styles à l’aide de sélecteurs qui ciblent l’élément interne (par exemple, en ajoutant une classe de wrapper et en utilisant des sélecteurs imbriqués) ou utilisez un mécanisme de création de thème recommandé pour les composants Jutro.
2. Préférez les API de création de thème documentées.
   • Le cas échéant, utilisez les API de remplacement de thème ou de style décrites dans la documentation du composant plutôt que de vous fier uniquement à className.

Pour en savoir plus, reportez-vous à la documentation des composants Jutro dans la section Référence de l’interface utilisateur Jutro.

Le composant de lien Jutro vers la propriété ne fonctionne pas comme attendu

Problème :
La propriété to du composant Lien ne navigue pas comme prévu ou renvoie à une route incorrecte.

Cause :
La configuration de routage de l’application ne correspond pas aux attentes du composant de lien Jutro (par exemple, contexte de routeur manquant, chemin de base incorrect ou incohérence entre les routes relatives et absolues).

Solution :

1. Confirmez la configuration du routeur.
   • Assurez-vous que l’application est encapsulée dans le fournisseur de routeur attendu et que le chemin de base est configuré de manière cohérente avec les routes utilisées par le composant de lien.
2. Testez la route individuellement.
   • Accédez directement à l’URL cible dans le navigateur pour vérifier qu’elle est valide et correctement diffusée.
3. Alignez-vous sur les exemples de routage.
   • Comparez votre utilisation du composant de lien avec les exemples de routage de la documentation Jutro et ajustez votre configuration en conséquence.

Pour en savoir plus, reportez-vous à la documentation des composants Jutro dans la section Référence de l’interface utilisateur Jutro.

Le comportement de test diffère selon les fuseaux horaires

Problème :
Les tests d’unités portant sur un comportement de date ou d’heure échouent lorsqu’ils sont exécutés dans des fuseaux horaires différents, même si la logique d’application reste inchangée.

Cause :
Les tests reposent sur le fuseau horaire du système local plutôt que sur un fuseau horaire de test fixe et explicite. Cela conduit à des attentes différentes en matière de formatage ou de calcul de la date et de l’heure selon les environnements.

Solution :

1. Normalisez le fuseau horaire du test.
   • Configurez votre exécuteur de tests pour qu’il utilise un fuseau horaire fixe (par exemple, UTC) et écrivez des assertions qui supposent ce fuseau horaire.
2. Évitez les heures locales codées en dur.
   • Utilisez une gestion explicite des dates prenant en compte le fuseau horaire dans les tests et le code d’application, et normalisez les heures en une référence cohérente lors de la comparaison des valeurs.

Pour en savoir plus, reportez-vous à la documentation sur les tests Jutro et les meilleures pratiques dans le guide des développeurs Jutro.

Conseils de gestion des états pour les applications Jutro

Problème :
Vous ne savez pas comment gérer au mieux un formulaire complexe ou l’état d’une application dans les applications Jutro, et vous ne savez pas s’il faut s’appuyer sur des modèles Jutro, des bibliothèques de gestion d’état externes ou une combinaison des deux.

Cause :
Jutro prend en charge plusieurs modèles de gestion de l’état, et la meilleure approche dépend de la complexité de votre application. Sans conseil, les équipes peuvent mélanger des modèles ou utiliser des bibliothèques externes d’une manière qui entre en conflit avec le mécanisme de liaison et de validation des données de Jutro.

Solution :

1. Commencez par les modèles Jutro documentés.
   • Privilégiez les modèles de gestion des états et des formulaires intégrés décrits dans la documentation Jutro pour les scénarios de workflow et CRUD courants.
2. Utilisez des bibliothèques externes lorsque cela est justifié.
   • Pour les applications plus volumineuses ou hautement interactives, vous pouvez utiliser des bibliothèques de gestion d’état externes, à condition :
     • De veiller à ce que la gestion des données sensibles en matière de sécurité soit alignée sur les recommandations de Jutro.
     • D'éviter de contourner le mécanisme de liaison des données de Jutro de manière à interférer avec la validation ou le contrôle d’accès.
3. Documentez le modèle que vous avez choisi en interne.
   • Enregistrez et partagez votre approche de gestion de l’état convenue au sein de votre équipe afin qu’elle soit appliquée de manière cohérente dans toutes les applications.

Résolution des problèmes liés au SDK Digital

Demandes envoyées avec des en-têtes de localisation manquants ou incorrects

Problème :
Les requêtes sortantes adressées à ClaimCenter, BillingCenter ou PolicyCenter sont envoyées avec des en-têtes de localisation manquants ou incorrects.

Cause :
Les en-têtes qui transmettent des informations de localisation ne sont pas automatiquement ajoutés aux requêtes du SDK Digital. Vous devez ajouter du code qui met à jour votre configuration pour inclure ces données dans les requêtes.

Note: Il s’agit d’une solution temporaire jusqu’à ce que le problème soit résolu dans une prochaine version. Lorsque le problème sera résolu, l’intercepteur sera automatiquement ajouté et vous pourrez supprimer le code de contournement.

Solution :

Pour ajouter l’intercepteur de localisation, effectuez les modifications suivantes au cours de l’étape d’initialisation de la configuration de votre SDK Digital :

1. Initialisez chaque SDK que vous utilisez (ClaimCenter, BillingCenter ou PolicyCenter).
2. Immédiatement après chaque appel d’initialisation, enregistrez un intercepteur de demande sur le restService du SDK.
3. Dans l’intercepteur, ajoutez les en-têtes GW-Language et GW-Locale à partir de vos valeurs actuelles de langue et de paramètre régional.

Le bloc de code suivant montre un exemple pour 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,
  },
}));