Mises à jour externes

Fonctionnalité

Sur le même principe que les webhooks qui permettent à un logiciel externe de mettre à jour des données dans Divalto weavy, on veut cette fois que Divalto weavy mette à jour des données dans un logiciel externe par l’intermédiaire notamment de webservices.

Tables

• sw_data_externaldataupdateasync : Table FIFO de mise à jour des données externes.

Champs

• sw_data_externaldataupdateasync.generictype_ID_status : Statut de la ligne dans la FIFO

  • Datatype : EXTERNAL_DATA_UPDATE_ASYNC_STATUS

  • Valeurs possibles :

    • TO_BE_TREATED : A traiter

    • TREATED : Traité

    • ERROR : En erreur

    • IGNORED : Ignoré

• sw_data_externaldataupdateasync.generictype_ID_action : Action à faire

  • Datatype : EXTERNAL_DATA_UPDATE_ASYNC_ACTION

  • Valeurs possibles :

    • INSERT : Ajout

    • UPDATE : Mise à jour

    • DELETE : Suppression

• sw_data_externaldataupdateasync.origin : Origine de l’enregistrement

  • Valeurs possibles :

    • NOTIFICATION : Enregistrement créé automatiquement par une notification

    • WORKSQUOTE : Enregistrement créé manuellement pour une demande de devis travaux

    • EVENT MEASURECOUNTER : Enregistrement créé par l’automate d’événement de gestion des relevés de compteurs (Manage ExtDataUpdateAsync - MeasureCounter)

• sw_data_externaldataupdateasync.entityBeforeValues et sw_data_externaldataupdateasync.entityAfterValues : Valeurs avant/après modification des champs suivis (au format json)

Exemple :

• sw_data_externaldataupdateasync.baseuser_ID : Utilisateur qui est à l’origine de la demande

Variables

• ExternalDataUpdateAsync.Retries : Nombre maximum de tentatives autorisées en cas d'erreur lors du traitement d'une ligne de sw_data_externaldataupdateasync

  • Valeur par défaut : 10

• ExternalDataUpdateAsync.BatchRecords : Nombre de lignes de sw_data_externaldataupdateasync à traiter dans un lot afin d'éviter le timeout de 30 s sur les notifications et events

  • Valeur par défaut : 5

• Portal.Administrator.Email : Email de l'administrateur utilisé pour l'envoi d'alertes (ex : nombre de tentatives de connexions API dépassé)

• MasterInfinity : Le projet utilise le master infinity. Permet d’activer certains automatismes comme par exemple la création de devis travaux dans Divalto infinity depuis le web Divalto weavy

  • Valeur par défaut : 0 (master) / 1 (master infinity)

Fonctionnement

Alimentation de la FIFO

• Automatique : A partir de la gestion des notifications sur une entité.
  A chaque évènement sur une entité (ajout, modification, suppression), un enregistrement est ajouté à la FIFO.
  Ici l'exemple du paramétrage standard pour l'ajout, la modification et la suppression d'un équipement.

  

• Manuel : pour les interventions et les demandes d'intervention lorsque l'utilisateur fait Créer un devis travaux.

• Event : pour les relevés de compteurs à une fréquence régulière car on a pas besoin de temps réel

Traitement de la FIFO

Les lignes de la FIFO dont le statut est A traiter ou En erreur sont traitées selon leur ordre d'arrivée (First In First Out).
Si une ligne est en erreur, on ne traite pas les lignes suivantes. Après n tentatives en échec (variable ExternalDataUpdateAsync.Retries) un mail est envoyé à un administrateur (variable Portal.Administrator.Email).

Exemple d'email :

Les lignes de la FIFO peuvent être traitées de plusieurs manières :

• Event : Automatiquement par paramétrage de l'automate Event « Manage ExtDataUpdateAsync flow ». Prévoir plutôt le soir.

• DataTracking : Automatiquement (via la notification ExtDataUpdateAsync) dès qu'un enregistrement est ajouté dans la FIFO .

• Manuel devis travaux : Lorsque l'utilisateur demande la création d'un devis travaux. Cette demande devient prioritaire (FIFO préemptive) et sera donc traitée avant les autres car on attend un retour côté web Divalto weavy. Si une erreur survient l'utilisateur est averti et l'enregistrement en erreur entrera dans le traitement normal de la FIFO.

• Manuel depuis la console web (Administration > Echanges externes) : Quand un utilisateur clique sur le bouton « Lancer le traitement des lignes »

Gestion de la FIFO

Une console d'administration appelée « Echanges externes » est disponible dans le menu « Administration ».
Elle permet de suivre le traitement des enregistrements de la FIFO avec possibilité de télécharger les json d'origine (données de la table weavy concernée) et le json envoyé à l'application externe.
On peut également statuer sur les éventuels enregistrements en erreur avec possibilité de :

• Ignorer : L'enregistrement est exclu du traitement de la FIFO (statut passé à IGNORED) et la ligne suivante pourra donc être traitée.

• Réessayer : Après n tentatives en erreur, le traitement est à l'arrêt et il y a donc possibilité de refaire un essai (statut passé à TO_BE_TREATED et nombre de tentatives remis à 0).

La possibilité est également donnée de lancer le traitement manuellement après avoir statué sur les erreurs (Bouton « Lancer le traitement des lignes »).

Paramétrage

L'interfaçage avec un logiciel externe demande forcément du scripting.
A cet effet il a été prévu plusieurs fonctions de surcharge afin de construire les modèles de données et de les transmettre :

• ManageExtDataUpdateAsyncOverload_Customeraddress : Déclenché si l’enregistrement de la FIFO concerne l’entité Adresse d’un tiers.

• ManageExtDataUpdateAsyncOverload_Equipment : Déclenché si l'enregistrement de la FIFO concerne l'entité Equipement.

• ManageExtDataUpdateAsyncOverload_Intervention : Déclenché si l'enregistrement de la FIFO concerne l'entité Intervention.

• ManageExtDataUpdateAsyncOverload_Interventionrequest : Déclenché si l'enregistrement de la FIFO concerne l'entité Demande d'intervention.

• ManageExtDataUpdateAsyncOverload_Measure : Déclenché si l’enregistrement de la FIFO concerne l’entité Mesure.

• ManageExtDataUpdateAsyncOverload_Productstockreplenishmentrequestheader : Déclenché si l’enregistrement de la FIFO concerne l’entité Entête de demande de réapprovisionnement.

• ManageExtDataUpdateAsyncOverload_Productstocktransferreceivedheader : Déclenché si l’enregistrement de la FIFO concerne l’entité Entête de réception de bon de transfert

• ManageExtDataUpdateAsyncOverload_Planning : Déclenché si l’enregistrement de la FIFO concerne l’entité Planning

• ManageExtDataUpdateAsyncOverload_xxxx : Déclenché si l'enregistrement de la FIFO concerne une entité non encore prévue en standard.

Exemple de script à surcharger pour les équipements :

// ManageExtDataUpdateAsyncOverload_Equipment
// @description                 => Manage equipment data to transmit on external software.
//
// @rowCode                     => codeequipemnt
// @rowID                       => equipment_ID
// @action                      => INSERT, UPDATE, DELETE
// @status                      => status in the fifo table : TO_BE_TREATED, ERROR
// @dataEntity                  => data from sw_data_equipment in json format
// @manualPreemptive            => user wait of infos (0/1)
// @origin                      => to identify the origin of the data
// @externaldataupdateasync_ID  => current fifo ID
// @entityBeforeValues          => json of values before change (depends if property DataTracking of the column is set in dictionary)
// @entityAfterValues           => json of values after change (depends if property DataTracking of the column is set in dictionary)
// @codebaseuser                => codebaseuser of the origin
//
// @returns                     => 0 : error / 1 : ok / 2 : ignored
//

rowCode                     = TRANSLATE( "<varscript>arg1</varscript>" )
rowID                       = TRANSLATE( "<varscript>arg2</varscript>" )
action                      = TRANSLATE( "<varscript>arg3</varscript>" )
status                      = TRANSLATE( "<varscript>arg4</varscript>" )
dataEntity                  = TRANSLATE( "<varscript>arg5</varscript>" )
manualPreemptive            = TRANSLATE( "<varscript>arg6</varscript>" )
origin                      = TRANSLATE( "<varscript>arg7</varscript>" )
externaldataupdateasync_ID  = TRANSLATE( "<varscript>arg8</varscript>" )
entityBeforeValues          = TRANSLATE( "<varscript>arg9</varscript>" )
entityAfterValues           = TRANSLATE( "<varscript>arg10</varscript>" )
codebaseuser                = TRANSLATE( "<varscript>arg11</varscript>" )

dataSent              = VARGET_SHELL( "dataSent", "ManageExtDataUpdateAsync" )
lastError             = VARGET_SHELL( "lastError", "ManageExtDataUpdateAsync" )
jsonDocReturnedInfos  = VARGET_SHELL( "jsonDocReturnedInfos", "ManageExtDataUpdateAsync" )


// To complete in overload


lastError = "Not supported in standard. You must manage the equipment data to sent in overload." // comment in overload

IF ( manualPreemptive == "1" ) THEN
  //if manualPreemptive we can return infos to user in json format
  //resultOk : 1=Ok, 0=Error
  //errorMessage : error message
  //returnedCode : code
  //returnedDetails : object of details
  //DOCUMENT_SET_PROPERTY_TO_OBJECT( jsonDocReturnedInfos, "resultOk", ... )
  //DOCUMENT_SET_PROPERTY_TO_OBJECT( jsonDocReturnedInfos, "errorMessage", ... )
  //DOCUMENT_SET_PROPERTY_TO_OBJECT( jsonDocReturnedInfos, "returnedCode", ... )
  //DOCUMENT_SET_PROPERTY_TO_OBJECT( jsonDocReturnedInfos, "returnedDetails", "property1", ... )
  //DOCUMENT_SET_PROPERTY_TO_OBJECT( jsonDocReturnedInfos, "returnedDetails", property2 ... )
ENDIF

VARSET_SHELL( "lastError", lastError , "ManageExtDataUpdateAsync" )
VARSET_SHELL( "dataSent", dataSent , "ManageExtDataUpdateAsync" )

RETURN( "0" ) // to be changed in overload (0 : error / 1 : ok)

Particularités

Une liaison avec Divalto infinity est implémentée en standard.
Les fonctions de script ont été surchargées au niveau DIVINF du master infinity afin de construire le json, d'appeler le webservice infinity et de gérer le retour.

Sont gérés :

• Gestion des équipements :

  • Versions : Divalto weavy 5.4 / Divalto infinity 10.6

  • Entité : Equipement

  • Origine : Notification (NOTIFICATION)

  • Code notification : ExtDataUpdateAsync_Equipment

  • Fonction surchargée : ManageExtDataUpdateAsyncOverload_Equipment

  • Webservice infinity : integration_equipement

  • Retours :

    • En création d’un nouvel équipement, recodification de sw_data_equipment.codeequipment avec GMMAT.RMCOD

  • Remarques :

    • A partir de Divalto weavy 6.0 / Divalto infinity 10.10, on gère la mise à jour des caractéristiques froid des équipements

• Création d’un devis travaux suite à intervention :

  • Versions : Divalto weavy 5.4 / Divalto infinity 10.6

  • Entité : Intervention

  • Origine : Manuelle (WORKSQUOTE)

  • Fonction surchargée : ManageExtDataUpdateAsyncOverload_Intervention

  • Webservice infinity : integration_dtr

  • Retours :

    • Mise à jour de sw_data_intervention.additionalExternalID avec PREFPINO + PINO + TICOD + PITYP

• Création d’un devis travaux sur demande d’intervention :

  • Versions : Divalto weavy 5.4 / Divalto infinity 10.6

  • Entité : Demande d’intervention

  • Origine : Manuelle (WORKSQUOTE)

  • Fonction surchargée : ManageExtDataUpdateAsyncOverload_Intervention

  • Webservice infinity : integration_dtr

  • Retours :

    • Mise à jour de sw_data_intervention.externalID avec PREFPINO + PINO + TICOD + PITYP

• Contrôle de réception bon de transfert :

  • Versions : Divalto weavy 5.5 / Divalto infinity 10.7

  • Entité : Entête de réception de bon de transfert

  • Origine : Notification (NOTIFICATION)

  • Code notification : ExtDataUpdateAsync_Productstocktransferreceivedheader

  • Fonction surchargée : ManageExtDataUpdateAsyncOverload_Productstocktransferreceivedheader

  • Webservice infinity : integration_bontransfert

  • Retours : /

• Avancement d’une intervention :

  • Versions : Divalto weavy 5.6 / Divalto infinity 10.8

  • Entité : Intervention / Planning

  • Origine : Notification (NOTIFICATION)

  • Code notification : ExtDataUpdateAsync_Intervention / ExtDataUpdateAsync_Planning

  • Fonction surchargée : ManageExtDataUpdateAsyncOverload_Intervention / ManageExtDataUpdateAsyncOverload_Planning → DIVINF_ManageExtDataUpdateAsync_InterventionAdvancement

  • Webservice infinity : integration_intervention

  • Retours : /

• Gestion des adresses d’un tiers :

  • Versions : Divalto weavy 5.7 / Divalto infinity 10.9

  • Entité : Tiers / Adresse

  • Origine : Notification (NOTIFICATION)

  • Code notification : ExtDataUpdateAsync_Customeraddress

  • Fonction surchargée : ManageExtDataUpdateAsyncOverload_Customeraddress

  • Webservice infinity : integration_adresse

  • Retours :

    • En création d’une nouvelle adresse

      • Recodification de sw_data_customeraddress.codecustomeraddress avec T1.TIERS + T1.ADRCOD

      • Mise à jour de sw_data_customeraddress.erpAddressID avec T1.ADRCOD

  • Remarques :

    • Utilisation de la variable ExternalDataUpdateAsync.Customeraddress.SyncType pour connaitre le type de synchronisation à effectuer :

      • 0 : Toutes les adresses

      • 1 : Uniquement les sites (valeur par défaut)

• Demande de réapprovisionnement :

  • Versions : Divalto weavy 5.7 / Divalto infinity 10.9

  • Entité : Entête de demande de réapprovisionnement

  • Origine : Notification (NOTIFICATION)

  • Code notification : ExtDataUpdateAsync_ProductstockReplenishmentrequestheader

  • Fonction surchargée : ManageExtDataUpdateAsyncOverload_Productstockreplenishmentrequestheader

  • Webservice infinity : integration_piece

  • Retours :

    • Mise à jour de :

      • sw_data_productstockreplenishmentrequestheader.externalID avec PREFPINO + PINO

      • sw_data_productstockreplenishmentrequestheader.processingDate à la date du jour

      • sw_data_productstockreplenishmentrequestheader.generictype_ID_status au statut Envoyé (dataType = 'PRODUCTSTOCK_REPLENISHMENTREQUEST_STATUS' et originalCode='SENT')

  • Remarques :

    • Ne sont transmises que les demandes de réapprovisionnement en statut Validé

    • Un réapprovisionnement peut être créé depuis une planification en prenant les pièces utilisées. Si la variable ReplenishmentAutoValidate (auto-validation du réapprovisionnement) est à 1 alors la demande de réapprovisionnement sera transmise automatiquement.

    • La demande de réapprovisionnement dans Divalto weavy va créer une commande de transfert dans Divalto infinity d’un dépôt non véhicule (par défaut dépôt principal) vers le dépôt du technicien

• Relevé de compteur d’un équipement :

  • Versions : Divalto weavy 5.7 / Divalto infinity 10.9

  • Entité : Mesure

  • Origine : Event (EVENT MEASURECOUNTER)

  • Code automate event : Manage ExtDataUpdateAsync - MeasureCounter

  • Fonction surchargée : ManageExtDataUpdateAsyncOverload_Measure

  • Webservice infinity : maj_cpt_equipement

  • Retours :

    • Mise à jour de sw_data_measure.srvExport à 0

  • Remarques :

    • On utilise un événement pour transmettre tous les derniers relevés de compteurs pour les équipements non exportés (sw_data_measure.srvExport=1) selon la fréquence paramétrée

• Création d’une affaire depuis une intervention :

  • Versions : Divalto weavy 6.0 / Divalto infinity 10.10

  • Entité : Intervention

  • Origine : Manuelle (DEAL)

  • Fonction surchargée : ManageExtDataUpdateAsyncOverload_Intervention → DIVINF_ManageExtDataUpdateAsync_InterventionDeal

  • Webservice infinity : integration_affaire

  • Retours :

    • Création d’une trace dans sw_data_interventionhistoryheader et sw_data_interventionhistorydetail pour l’intervention concernée en cas de réussite ou d'échec du webservice

  • Remarques :

    • Après la création de l’affaire dans Divalto infinity, on enchaine automatiquement sur les traitements suivants à travers l’ICP :

      • Appel du Webhook “Deal” pour créer l’affaire dans Divalto weavy

      • Appel du Webhook “Intervention” pour lier l’affaire, l'élément d’affaire et l’activité à l’intervention dans Divalto weavy

// DIVINF_Func_GetInfinityWebServiceInfo
// @description => Get infos for webservice infinity
// @returns     => 0 : error / 1 : ok
// @returned variables
// InfinityWebServiceUrl : Infinity server URL for the call of the WebService
// InfinityWebServiceAction : Infinity diva action to push in the web method
// InfinityWebServiceErrorMsg : Error message if returns is 0

InfinityWebServiceUrl     = VARGET_DBSQL( "select url from sw_data_externalurl where codeexternalurl='WSDIVA'" )
InfinityWebServiceAction  = "WEB_SERVICE_INFINITY"
InfinityWebServiceErrorMsg   = ""
ret = 1

IF (EQUALS( InfinityWebServiceUrl, "" )) THEN
  InfinityWebServiceErrorMsg = "Infinity server URL for the call of the WebService is not informed (Table=sw_data_externalurl, Code='WSDIVA')"
  ret = 0
ENDIF

VARSET_SHELL( "InfinityWebServiceUrl", InfinityWebServiceUrl, "InfinityWSinfo" )
VARSET_SHELL( "InfinityWebServiceAction", InfinityWebServiceAction, "InfinityWSinfo" )
VARSET_SHELL( "InfinityWebServiceErrorMsg", InfinityWebServiceErrorMsg, "InfinityWSinfo" )

RETURN( ret )

"header": {
  "caller": "weavy", // Défini en dur
  "callerVersion": "1.6.20231121", // Version du Master (variable MasterVersion)
  "languageCode": "FR", // Défini en dur
  "userCode": "MD", // Code de l'utilisateur à l'origine de la demande (sw_data_baseuser.codebaseuser) ou si pas connu, nom de l'utilisateur système qui fait l'envoi (en général NotificationScriptUser)
  "callDateTime": "2023-12-08 11:23:32" // Date et heure de l'envoi
}