3-Installation technique et Mises à jour
Contexte et objectif
Ce chapitre décrit l’installation technique du connecteur Yooz pour Sage X3. La procédure s’appuie sur les fonctions standard de Sage X3 et s’applique aux versions courantes de Sage X3 v12. L’installation est réalisée par intégration de patchs X3 en couche verticale, complétée par l’import de fichiers JSON, la création d’une tâche récurrente et le paramétrage du pool de Web Services SOAP.
Ce chapitre précise les modes opératoires pour :
-
La récupération du package technique d'installation du connecteur Yooz.
-
L’intégration des patchs spécifiques en couche verticale dans Sage X3.
-
La création et l'activation de la tâche de synchronisation des Web Services.
Ce document intervient sur ces phases de l’implémentation :
| ▼ | ||||||
|---|---|---|---|---|---|---|
| Avant-vente | Initialisation | Cadrage | Installation | Paramétrage | Recette | Mise en production |
Prérequis et préparation
Avant de débuter l'installation technique du connecteur, il est impératif d'avoir généré et intégré le fichier Serial Yooz sur la solution Sage X3 de votre client (voir 0-Obtention et activation du serial).
- Droits nécessaires : Se connecter à Sage X3 avec un compte ADMIN ou un utilisateur possédant le badge ERPDEV.
- Langue de session : Standard (ENG ou FRA).
- Disponibilité système : L'installation complète ne prend pas plus que 3 heures.
L'étape 1 du déploiement (Mise à jour des tables standards) est la seule opération qui exige la déconnexion totale de tous les utilisateurs. Les étapes suivantes peuvent être réalisées avec des sessions actives.
Mode opératoire
1 Téléchargement du package d’installation
- Télécharger le fichier pour l’installation (fichier ZIP)
📄 Télécharger le pack d'installation V12
Format :.zip — Taille : 7.1 MB — Version : v1.105- Le mot de passe pour le fichier ZIP est transmis avec le fichier serial, si ce n’est pas le cas vous pouvez revenir vers votre contact Yooz.
Versioning
Les informations relatives au versioning du connecteur Yooz pour Sage X3 sont disponibles dans la section Release Notes du site web. Cela permet de consulter les versions disponibles du connecteur, ainsi que les informations associées aux évolutions, corrections ou mises à jour publiées.
2 Intégration des patchs
Préparation des fichiers patchs (optionnel)
Cette étape est optionnelle. Elle est nécessaire uniquement si les patchs doivent être intégrés depuis le serveur d’application Sage X3.
1. Copier l’archive récupérée à l’étape précédente dans le sous-répertoire <PATCH> du dossier cible X3.
2. Décompresser l’archive dans ce répertoire.
3. Vérifier que les répertoires Step1, Step2, Step3, Step4, Json (ou Step5 selon la version du patch) et le fichier PatchFiles.xlsx sont présents dans le package.
Si l’accès au serveur d’application X3 n’est pas disponible, l’intégration de patch peut être effectuée avec le type de destination Client. Dans ce cas, les fichiers sont intégrés un par un depuis le poste de travail.
Intégration des 3 premiers patchs
Les trois premières étapes d’intégration s’effectuent depuis la même fonction Sage X3.
1. Ouvrir la fonction Intégration de patchs par le menu : Développement > Utilitaires > Patchs > Intégration de patch (fonction PATCH)
2. Pour chaque étape, renseigner le champ Patch avec le chemin correspondant, puis lancer l’intégration.
| Étape | Chemin à renseigner dans le champ Patch | Point de vigilance |
|---|---|---|
| Step1 | [PATCH]/YoozConnectorSageX3-Installation/Step1 | Cette étape met à jour des tables standards. Elle doit impérativement être réalisée sans aucune session utilisateur active. |
| Step2 | [PATCH]/YoozConnectorSageX3-Installation/Step2 | Peut être réalisée avec des sessions utilisateurs actives. |
| Step3 | [PATCH]/YoozConnectorSageX3-Installation/Step3 | Peut être réalisée avec des sessions utilisateurs actives. |
3. Lancer l’intégration du patch puis attendre l’affichage de la trace avant de continuer.
La trace ne doit contenir ni warning ni erreur. Si une anomalie est présente, elle doit être analysée et corrigée avant de poursuivre l’installation.
Intégration du patch Step4 - Mise à jour des objets standards
Le Step4 concerne la mise à jour d’éléments standards, principalement des écrans standards Sage X3.
Le fichier PatchFiles.xlsx, disponible dans le répertoire de documentation du package, permet d’identifier les objets concernés par Step4.
Deux approches sont possibles :
Option 1 - intégration par patch : à privilégier lorsque le niveau de patch Sage X3 est compatible avec le patch fourni.
Option 2 - mises à jour manuelles : à privilégier si la solution Sage X3 n’est pas au dernier niveau de patch, ou si les objets standards ont déjà été adaptés. Dans ce cas, les modifications sont saisies manuellement à partir du fichier PatchFiles.xlsx.
Option 1 - Intégration du patch Step4
1. Ouvrir la fonction Intégration de patchs par le menu : Développement > Utilitaires > Patchs > Intégration de patch (fonction PATCH)
2. Renseigner le champ Patch tel que [PATCH]/YoozConnectorSageX3-Installation/Step4
3. Lancer l’intégration du patch puis attendre l’affichage de la trace avant de continuer.
La trace ne doit contenir ni warning ni erreur. Si une anomalie est présente, elle doit être analysée et corrigée avant de poursuivre l’installation.
Option 2 - Mises à jour manuelles
1. Ne pas intégrer le patch Step4 dans Sage X3.
2. Ouvrir le fichier PatchFiles.xlsx et appliquer manuellement les modifications listées pour les objets cochés en Step4.
3. Après saisie des modifications, valider les objets concernés et vérifier qu’aucune erreur de validation n’est présente.
Les codes des boutons du connecteur ajoutés dans les fenêtres standard n’ont pas d’importance. Si le code par défaut est déjà pris pour un autre bouton dans votre application, vous pouvez utiliser un autre code. Vous trouverez plus d’informations sur les boutons à créer dans le fichier YoozConnectorX3-PatchFiles.xlsx présent dans le dossier Documentation du pack d’installation.
3 Import des fichiers JSON
Cette étape peut être réalisée à tout moment, avec des sessions utilisateurs actives.
Ouvrir l’assistant d’import par le menu : Administration > Utilitaires > Imports > Outils d’import
1. Sélectionner l’option Client JSON file.
2. Cliquer sur Select file.
3. Sélectionner un fichier JSON dans le répertoire Json du package d’installation. Selon le package utilisé, le répertoire peut aussi être indiqué comme Step5.
4. Répéter l’opération pour chaque fichier JSON à importer.
5. Se reconnecter à Sage X3 après l’import. Les nouveaux menus Yooz deviennent alors disponibles. Ils peuvent être retrouvés en saisissant Yooz dans la barre de recherche du menu.
4 Création de la tâche récurrente XRJ31EXE
La tâche et la tâche récurrente ne sont pas livrées par patch, car ces données sont stockées dans le dossier X3. Cette tâche permet d’automatiser les traitements de synchronisation du connecteur Yooz X3, afin d’assurer les échanges réguliers entre Sage X3 et Yooz via les Web Services.
-
Créer d’abord la tâche batch dans la fonction : Exploitation > Serveur batch > Gestion des tâches (fonction GESABT)
-
Créer une tâche de code XRJ31EXE, basée sur la fonction XRJ31EXE.
-
Créer ensuite la tâche récurrente : Exploitation > Serveur batch > Gestion des abonnements (fonction GESABA)
-
Créer une tâche récurrente basée sur la tâche XRJ31EXE. Elle doit être planifiée avec une fréquence élevée afin de maintenir une bonne synchronisation entre Sage X3 et Yooz.
- Cliquer sur le bouton Paramètres et cocher les cases en face des objets à synchroniser. Si vous devez changer par la suite ces paramètres, il faudra désactiver et réactiver l’abonnement.
Avant d’activer l’abonnement (cocher la case Actif), vous devez vous synchroniser avec l’équipe projet ou les K-users fonctionnels.
5 Paramétrage du user Yooz (dans les modules Administration et Paramétrage)
Cette étape permet de préparer le compte technique utilisé par le connecteur et par les appels Web Services. Le compte doit être disponible dans l’administration Sage X3 / Syracuse et rattaché au bon endpoint.
1. Ouvrir Administration > Administration > Utilisateurs.
2. Créer ou contrôler le user technique Yooz prévu pour le connecteur.
3. Renseigner les endpoints nécessaires. Le user doit pouvoir accéder au dossier X3 concerné.
4. Ajouter les groupes et rôles nécessaires selon la politique d’habilitation du client.
5. Vérifier que le compte est actif et que le mot de passe est connu au moment de créer le pool de Web Services.
Le user technique utilisé par le pool SOAP doit être stable. Éviter les comptes nominatifs, car une désactivation utilisateur ou un changement de mot de passe peut interrompre les flux Yooz vers Sage X3.
Le user Yooz doit également être contrôlé dans les fonctions de paramétrage X3. Il est utilisé dans les propriétés objets lors des retours ou des imports depuis l’application Yooz.
1. Ouvrir Paramétrage > Utilisateurs > Utilisateurs (fonction GESAUS).
2. Créer ou contrôler l’utilisateur YOOZ utilisé par le connecteur.
3. Ajouter l’adresse e-mail de workflow lorsque le projet prévoit l’envoi de notifications ou de traces.
4. Contrôler les habilitations X3, l’accès au dossier et les droits nécessaires sur les objets traités par le connecteur.
5. Enregistrer puis valider l’utilisateur si la fonction le demande.
NOTE : Le user Yooz doit être cohérent entre l’administration Syracuse, le setup X3 et le pool de Web Services. Les écarts de droits entre ces trois niveaux sont une cause fréquente d’erreurs de connexion ou de traitements en échec.
7 Création du Pool de Web Services SOAP Yooz
Le pool de Web Services SOAP permet à Yooz d’appeler les Web Services Sage X3. Il s’agit du point technique utilisé par les flux entrants depuis Yooz vers X3, notamment pour les imports ou retours gérés par le connecteur.
Ouvrir la fonction : Administration > Administration > Web services.
1. Ajouter l’endpoint correspondant au dossier Sage X3 concerné.
2. Ajouter un user disposant des droits nécessaires. Le user doit être celui préparé dans les étapes précédentes ou un compte technique équivalent.
3. Créer un pool par endpoint. Lorsque plusieurs dossiers ou endpoints sont exposés, chacun doit disposer de son propre pool.
4. Renseigner un alias de pool explicite. Cet alias est communiqué à Yooz avec le mot de passe associé.
5. Contrôler que le user du pool dispose de droits suffisants pour exécuter les services nécessaires au connecteur.
6. Enregistrer la configuration du pool et vérifier qu’aucune erreur n’est signalée dans l’administration.
Après la création du pool, effectuer une publication globale depuis la fonction GESAWE de tous les Web Services AOWS*. Cette publication rend les Web Services nécessaires disponibles pour les appels SOAP du connecteur.
1. Ouvrir la fonction Développement > Dictionnaire des scripts > Scripts > Web services (fonction GESAWE)
2. Filtrer les Web Services AOWS*.
3. Lancer la publication globale.
4. Contrôler que la publication est terminée sans erreur.
Transmettre à Yooz uniquement les éléments nécessaires : l’URL SOAP publiée, le code alias du pool et le mot de passe associé. Ne pas transmettre de captures contenant des secrets ou des mots de passe visibles.
NOTE : Le chemin SOAP attendu par Yooz doit être accessible depuis l’extérieur selon l’architecture validée : /soap-generic/syracuse/collaboration/syracuse/CAdxWebServiceXmlCC. Lorsque l’accès passe par un reverse proxy, vérifier que ce chemin est bien routé vers Sage X3.
8 Ajout du badge YOOZ aux Rôles
Le badge YOOZ est créé lors de l’intégration du serial. Il doit être ajouté aux rôles des utilisateurs qui exploitent le connecteur, ainsi qu’au rôle utilisé par le compte technique ou par le serveur batch.
1. Ouvrir Administration > Utilisateurs > Rôles.
2. Identifier les rôles utilisés par les utilisateurs du connecteur Yooz X3.
3. Ajouter le badge YOOZ aux rôles concernés.
4. Ajouter également le badge YOOZ au rôle affecté au compte utilisé par le serveur batch et/ou le pool Web Services.
5. Demander une reconnexion des utilisateurs si nécessaire afin que les nouveaux droits soient pris en compte.
Ne pas oublier le rôle du batch server. Si le badge YOOZ n’est pas affecté au compte qui exécute XRJ31EXE, les traitements automatiques peuvent échouer même si les utilisateurs interactifs disposent des droits nécessaires.
9 Étape complémentaire : Patch Hotfix
Le package d’installation peut contenir un sous-répertoire Hotfix. Cette étape est à réaliser uniquement si des fichiers sont présents dans ce répertoire.
1. Contrôler dans le package la présence du répertoire Hotfix.
2. S’il contient des fichiers, ouvrir la fonction Intégration de patchs : Développement > Utilitaires > Patchs > Intégration de patch (fonction PATCH).
3. Renseigner le champ Patch avec le chemin [PATCH]/YoozConnectorSageX3-Installation/Hotfix.
4. Lancer l’intégration du patch, puis attendre l’affichage de la trace avant de continuer.
5. Analyser la trace. Elle ne doit contenir ni warning ni erreur.
NOTE : L’étape Hotfix suit la même logique que les patchs Step2 ou Step3 : intégrer, attendre la trace, puis traiter toute anomalie avant de poursuivre.
10 Paramètres techniques de connexion Yooz
La méthode d’authentification disponible avec Yooz est basée sur Client ID / Client Secret. L’équipe Yooz doit autoriser Deveho comme partenaire, définir les droits dans l’application Yooz et communiquer les identifiants nécessaires au projet.
10.1 Paramètres de connexion
Ouvrir la fonction : Paramètres > Paramètres généraux > Valeurs paramètres (fonction ADPVAL), chapitre EXAPP, groupe YOOZ.
| Paramètre | Rôle / utilisation | Vigilance |
|---|---|---|
| XRJ31APPID | Identifiant de l’application Yooz appelée par Sage X3. | Valeur fournie par le PM Yooz. Obligatoire. |
| XRJ31CLIID | Identifiant client utilisé pour l’authentification API / OAuth. | Si incorrect : authentification refusée. |
| XRJ31CLISC | Secret client utilisé avec le Client ID. | Donnée confidentielle à ne pas exposer dans les captures. |
| XRJ31URLDO | URL Yooz de l’environnement cible : test, préproduction ou production. | Vérifier que l’URL correspond bien aux identifiants fournis. |
| XRJ31TIMZO | Fuseau horaire utilisé dans les échanges, ex. Europe/Paris. | Si incorrect : risque de décalage de dates/heures. |
| XRJ31USRLA | Langue utilisée dans les échanges, ex. fr ou en. | Si incorrect : langue inattendue côté Yooz. |
Avant tout test de flux, vérifier que l’URL Yooz, l’Application ID, le Client ID et le Client Secret correspondent au même environnement. Un mélange de valeurs test et production peut envoyer des données au mauvais environnement.
10.2 Options Curl et configuration proxy
Lors de l’envoi de certains documents, comme les commandes d’achat ou les réceptions, le connecteur utilise une commande Curl pour communiquer avec Yooz. Le paramètre XRJ31CURLO permet d’ajouter des options techniques à la requête.
1. Ouvrir Paramètres > Paramètres généraux > Valeurs paramètres (chapitre EXAPP, groupe YOOZ).
2. Renseigner le paramètre XRJ31CURLO uniquement si une option technique est nécessaire.
3. Dans le cas d’un réseau protégé par un proxy, utiliser une option de type : -x <[protocol://][user:password@]proxyhost[:port]>.
4. Tester l’envoi d’un document après modification afin de contrôler que le proxy ou l’option ajoutée ne bloque pas l’appel Yooz.
Ne pas renseigner d’option Curl sans validation de l’équipe infrastructure. Une option incorrecte peut bloquer tous les flux sortants REST vers Yooz.
10.3 Gestion de deux applications Yooz sur un même environnement X3
Lorsque le même environnement X3 porte plusieurs dossiers, par exemple un dossier de test et un dossier de production, il peut être nécessaire de gérer deux applications Yooz distinctes depuis le même environnement technique.
1. Ouvrir Administration > Administration > Web services > Rest web services.
2. Dupliquer les deux Web Services REST avec un nouveau code lorsque le projet nécessite deux applications Yooz.
3. Renseigner ensuite les valeurs paramètres dédiées dans Paramètres > Paramètres généraux > Valeurs paramètres (chapitre EXAPP, groupe YOOZ).
4. Utiliser XRJ31RESTT et XRJ31RESTY pour indiquer les codes de Web Services REST à utiliser pour l’application Yooz complémentaire.
5. Si les environnements Sage X3 sont séparés physiquement ou techniquement, ces paramètres spécifiques ne sont généralement pas nécessaires
Lorsque deux applications Yooz doivent être alimentées depuis le même dossier X3, contrôler XRJ31RESTT et XRJ31RESTY avant les reprises de référentiels et avant l’activation de XRJ31EXE.
11 Procédure de mise à jour automatique du connecteur (XRJ31UPD)
La fonction Yooz connector update permet de mettre à jour le connecteur depuis Sage X3. Elle doit être utilisée lorsque la version cible du connecteur nécessite une mise à jour du noyau du connecteur, de certains champs techniques, d’index, d’écrans standards ou de fonctions complémentaires.
Ouvrir la fonction : Usage > Imports / exports > Yooz connector update (fonction XRJ31UPD).
-
Mettre à jour le noyau spécifique du connecteur Yooz X3.
-
Ajouter les champs et index manquants sur les tables standards lorsque la version cible le requiert.
-
Ajouter les champs nécessaires sur les écrans standards concernés.
-
Ajouter les fonctions complémentaires livrées dans la version cible : Importer les fichiers JSON associés à la nouvelle version via Administration > Utilitaires > Imports > Outils d’import.
NOTE : Si le client ne souhaite pas patcher les éléments standards, appliquer manuellement les modifications décrites dans le fichier PatchFiles.xlsx.
12 Paramètre complémentaire côté Yooz
Une étape complémentaire peut être nécessaire dans l’application Yooz, notamment pour les retours de paiement vers Sage X3.
1. Ouvrir l’application Yooz avec un utilisateur disposant des droits d’administration nécessaires.
2. Accéder à la section Advanced parameters.
3. Contrôler le paramètre relatif à la réimportation d’un fichier avec le même checksum.
4. Positionner le paramètre à Off lorsque le flux de retour de paiement Yooz vers Sage X3 l’exige.
5. Valider le changement avec le chef de projet Yooz avant de lancer les tests de feedback paiement.
Ce paramètre est côté Yooz. Il doit être modifié uniquement lorsque le flux projet le nécessite et après validation par l’équipe Yooz.