Les widgets KPI se caractérisent par l'utilisation directe d'une requête SQL pour lire les données en base de données ou le paramétrage via un fichier texte contenant des requêtes SQL de type select.

Particularités des widgets KPI

• Configuration du widget via un assistant dans le zoom des widgets
• Conversion du résultat de la requête SQL en chaîne de paramétrage pour le widget selon son type de widget
• Widgets concernés par le mode KPI : feu, jauge, graphique, liste
• Utilisation de paramètres ERP (utilisateur courant, dossier courant, …) dans l'écriture de la requête
• Fréquence de rafraîchissement choisie dans le widget
• Structure de données imposée par le type de widget
• Ordre des champs
• Type des champs
• Nombre de champs significatifs
• Fonction de TEST du widget pour vérifier la requête
• Fonction de SIMULATION du widget pour vérifier le résultat
• Fonction de DEBUG en exécution
• Vues SQL Server pour simplifier l'écriture des requêtes
• Vues ERP
• Vues KPI
• Traitement des confidentialités ERP
• Utilisation des balises ERROR des widgets

Assistant widget KPI

L'assistant 'mode KPI' des widgets couvre trois fonctions dans le zoom des widgets (appelé depuis l'IA par Ctrl+F7) :

• Aide au remplissage des champs du zoom des widgets via la case à cocher et la liste déroulante
• Test du mode KPI via le menu dédié
• Simulation du mode KPI via le menu dédié

L'assistant se base sur la présence d'un fichier exemple « Indicateur.drpt » et sur les fichiers nommés "'CodeApplic'_Indicateur.drpt" comme par exemple « DAV_Indicateur.drpt » présent dans les implicites ERP.
La case à cocher va charger tous les modes KPI décrits dans le fichier et les proposer dans la liste déroulante.
Le choix d'un élément de la liste va garnir les champs du widget. Les données sont modifiables par la suite.

Quelques règles de fonctionnement :
L'assistant considère toujours « Indicateur.drpt » ou les fichiers nommé "CodeApplic_Indicateur.drpt" comme par exemple « DAV_Indicateur.drpt » (mais il reste modifiable dans la zone paramétrage)
Une alternative est aussi le nommage "CodeApplic_U_Indicateur.drpt" comme par exemple « DAV_U_Indicateur.drpt » pour des fichiers complémentaires distincts
Le nom ainsi que la balise du KPI sont indispensables
La fréquence de rafraîchissement ne doit pas être trop élevée au risque du surcharger le serveur SQL
Les noms du module et fonction sont indispensables. L'assistant les positionne après choix dans la liste
Le widget sera vide dans l'IA si le paramétrage (du widget) n'est pas bon
Attention, la visite guidée propose des exemples pour une version minimale de SQL 2012. L'utilisation de version antérieure provoque une erreur SQL.

TESTER une requête SQL associée au widget KPI

Le menu "WidgetKPI / Générer la requête dans le presse-papier permet de tester le widget KPI" permet de tester le paramétrage :
Lecture du fichier indiqué pour le widget

• Permet de vérifier si le fichier est trouvé
• Permet de vérifier si le KPI est trouvé dans le fichier
• Permet surtout d'exécuter la requête afin de vérifier sa validité (en termes d'écriture SQL)

La requête est copiée dans le presse-papier pour exécution dans SQL Management studio

SIMULER le résultat du widget KPI

Le menu "WidgetKPI / Copier le résultat du KPI dans le presse-papier" permet de simuler le widget en mode KPI.
Après avoir exécuté la requête, passe par la conversion du résultat de la requête SQL en chaîne au format requis par le widget choisi.
Le résultat est copié dans le presse-papier pour vérification dans un bloc-notes.

Paramétrage du fichier de descriptions des KPI

Le fichier de description des KPI est un fichier texte, placé dans l'implicite ERP, et indiqué dans la zone texte de paramétrage du widget. Le nom pris par défaut est : Indicateur.drpt
L'assistant considère toujours « Indicateur.drpt » ou les fichiers nommé "CodeApplic_Indicateur.drpt" comme par exemple « DAV_Indicateur.drpt » (mais il reste modifiable dans la zone paramétrage)
Une alternative est aussi le nommage "CodeApplic_U_Indicateur.drpt" comme par exemple « DAV_U_Indicateur.drpt » pour des fichiers complémentaires distincts.

STRUCTURE COMPLETE

CODE UNIQUE DU WIDGET : Commentaire pour le zoom des widgets
C'est le code du KPI qui doit être unique par fichier. Il sert au widget à trouver la définition du KPI et il est affiché dans la liste déroulante de l'assistant. Le commentaire apparaît dans la bulle de la liste déroulante de l'assistant

Balise TYPE à F ou FEU, J ou JAUGE, L ou LIST, G ou GRAPHIQUE pour restreindre le choix du zoom des widgets
Pour restreindre le choix du zoom des widgets dans la liste déroulante de l'assistant. Une seule lettre suffit : F, J, L ou G.
Les FEU et JAUGE ont la même structure pour le KPI, cela signifie que l'on peut mettre la balise TYPE à FJ systématiquement.
Le widget TABLEAU est un widget LISTE qui retourne plusieurs colonnes, c'est donc la requête SQL qui détermine le type. Pour les graphiques, le type de graphiques (camembert ou histogramme) est déterminé par la requête SQL.

Balise MAX à 50 nombre maximum de lignes pour un widget liste.
Valeur numérique entière. Le widget LISTE a une valeur par défaut de 100 lignes affichées au maximum (ne concerne pas les autres widgets). Pour modifier cette limite, indiquer le nombre de lignes maximum à afficher
Pour ne pas avoir de limite mettre la valeur 0
Balise QUERY. Ma requête en plusieurs lignes avec des paramètres sous la forme @NOMPARAM et la database sous la forme $APPLIC. devant le nom de la table.
Écriture de la requête SQL de type SELECT Multi-ligne autorisé. Permet l'utilisation de paramètres au niveau ERP et requête. Accepte les UNION ou les variables SQL Server ou les fonctions SQL Server.
Doit être compatible avec la cible de version de serveur de base de données (SQL Server 2012 dans les exemple fournis)

Balise DEBUG à E ou R ou ER active un mode débogage lors de l'exécution du widget dans l'IA. La présence de la balise DEBUG associée à la valeur E ou R active un mode débogage lors de l'exécution du widget dans l'IA.
E = demande confirmation d'exécution de la requête, et permet de copier la requête dans le presse-papier
R = copie du résultat dans le presse-papier (ER fait les deux actions)
Pour désactiver le debug, il suffit de renommer la balise en NODEBUG pour qu'elle ne soit plus reconnue.

Balise ZOOM à CODE_APPLIC : Numéro du zoom utilisé pour les widgets LISTE pour trouver le code application et le numéro de zoom à appeler en standard; Possibilité de surcharge a5tmetlkpi.dhsp pour traiter d'autres actions.
CODE_APPLIC indique le nom du module concerné (DAV COMMUN DCPT DCONT DPAIE DRT DQUAL DAFF DDOC DGRM DSP DREG)
Numéro du zoom : numéro interne du zoom (Shift+f7 dans l'IA) Utilisé pour les widgets KPI LISTE pour trouver le code application et le numéro de zoom à appeler. En standard en cas de clic sur la ligne, possibilité de surcharger a5tmetlkpi.dhsp pour traiter d'autres actions

COMPLEMENTS
Paramètres de requêtes SQL : contexte ERP

L'écriture des requêtes SQL permet l'utilisation de paramètres de contexte ERP. Ce sont des données liées à l'exécution courante de l'ERP (à partir de l'IA) qui sont disponibles pour filtrer.

Le filtrage contextuel ERP est indispensable pour une bonne utilisation des KPI. Le zoom des widgets fonctionnant hors contexte ERP, la fonction de TEST de l'assistant utilise un module diva 'a5tmetlkpi' qui effectue le garnissage des données pour permettre la substitution des valeurs.
Paramètres de requêtes SQL : globale
A mettre en début de fichier dans une section KPI vide (=crochet ouvrant immédiatement suivi d'un crochet fermant). Ces paramètres seront valables pour tout le fichier.

Paramètres de requêtes SQL
Dans le zoom des widgets, il est possible d'attribuer une valeur à un paramètre dans la zone de texte du zoom des widgets (avec les balises INDICATEUR).
Ce paramètre, sous la forme @NOMPARAM sera valable pour ce widget uniquement. Il est prioritaire aux paramètres globaux ou locaux

Nom de base de données
La requête SQL est exécutée par la couche runtime (record diva SQL) et gère donc la répartition sur plusieurs bases de données. Notamment, la base de données décisionnelle (DataWarehouse)ou encore le module comptabilité ou paie qui serait hébergé dans une autre base.
Syntaxe : identique à celle de l'écriture des record SQL, à savoir $MADATABASE.NOMTABLE
Les valeurs possibles pour $MADATABASE sont : $DAV $BI $COMMUN $DCPT $DCONT $DPAIE $DRT $DQUAL $DAFF $DDOC $DGRM $DSP $DREG
Lorsque $MADATABASE n'est pas indiqué c'est la base de données $COMMUN qui est utilisée.
Base BI : ce mécanisme permet donc d'afficher dans l'IA des widgets qui interrogent directement la base SQL décisionnelle.
Exemple:
SELECT SUM(MAXFAC.MONTANT_FACTURE_NET_DEV) FROM $BI.F_FACTURE_VENTE_LIGNE as MAXFAC WHERE YEAR(MAXFAC.DATE_FACTURE) = YEAR(GETDATE())-1 and MAXFAC.DOSSIER_CODE = @DOSSIER
Action KPI sur widget liste
Une première action consiste à utiliser le paramétrage d'appel de zoom possible dans le fichier de paramétrage. Cette option implique que le champ ID rendu par le widget soit exploitable par le zoom puisque celui-ci le reçoit dans la zone de pilotage Harmony.DataVal.
Une alternative consiste à construire dans la requête SQL une chaîne sous la forme nommodule;nomfonction;liste param séparée par des ';' qui permet d'adresser un module Diva et de faire appel à une fonction tunnel
Exemple: une liste OF construit
GGPMBAS.DHOP;Tunnel_OF_Visualiser;"597"
GGPMBAS.DHOP;Tunnel_OF_Visualiser;"643"
Ce qui permet d'appel la fonction Diva "Tunnel_OF_Visualiser" du module "GGPMBAS.DHOP" avec en paramètre le numéro d'OF à consulter
3 actions différentes sont possibles :

• Sur double-clic gauche: appel de l'action retournée dans le champ ACTIONKPI
• Sur double-clic et touche CTRL : appel de l'action retournée dans le champ ACTIONKPIC
• Sur double-clic et touche SHIFT : appel de l'action retournée dans le champ ACTIONKPIS

L'appel d'une fonction nécessite de respecter des règles

• ; entre les paramètres de la fonction ou procédure
• Pas de constante diva, il faut donner les valeurs
• Mettre des " pour sécuriser les espaces utiles dans les chaînes

Exemple de syntaxe pour ouvrir une pièce
CONCAT('gtpm000.dhop;Tunnel_Piece_Consulter;"', ENT.TICOD , '";' , ENT.PICOD ,
';"',dbo.PIECECONCAT(ENT.PREFPINO ,ENT.PINO), '";1;1') as ACTIONKPI,
Traitement des confidentialités ERP
Il est possible de traiter les confidentialités ERP. Le champ CONF doit être garni avec la confidentialité issue de la requête SQL ou imposée par le paramétrage KPI dans la requête.
Le traitement du champ CONF suit exactement les mêmes règles que dans l'ERP
Utilisation des balises ERROR des widgets
Tous les widgets traitent une balise ERROR
N'est utilisé qu'en l'absence de licence pour l'indiquer dans l'IA

Widgets en mode KPI

L'utilisation du mode KPI permet de convertir des données issues d'une requête SQL en chaine de caractères exploitables par le widget (tel qu'il l'attend).
Pour cela le RESULTAT DE LA REQUETE doit respecter l'ordre et le type des champs. Les champs non retournés par la requête ont une valeur par défaut. Il n'est donc pas nécessaire de retourner TOUS les champs requis par le KPI.
Le nom des champs n'est pas significatif (c'est bien l'ordre des champs) mais il est recommandé de les mettre pour une meilleure lecture de la requête SQL.
Par contre l'ORDRE DES CHAMPS et la NATURE DES CHAMPS sont fondamentaux, à respecter selon le dictionnaire (et pas selon l'aide Runtime)
La première colonne est toujours un ID qui ne figure pas dans le dictionnaire mais il est indispensable à la couche Runtime
FEU / JAUGE

FEU

• (Valeur minimale inutile pour un feu)
• Valeur maximale
• Valeur courante numérique
• Etat (couleur)
• Ecart par rapport à l'objectif
• Valeur courante formatée en texte
• Titre du widget

JAUGE

• Valeur minimale
• Valeur maximale
• Valeur courante numérique
• Etat (couleur)
• Ecart par rapport à l'objectif
• Valeur courante formatée en texte
• Titre du widget

CHAMPS ATTENDUS EN RETOUR DE LA REQUETE SQL
La requête ne doit retourner qu'UNE seule ligne

LISTE/TABLEAU

Liste

• Texte à afficher
• Titre du widget
• Priorité de l'élément (couleur)
• ActionKPI permettant de déterminer l'action sur double-clic dans le widget
• ActionKPIC permettant de déterminer l'action sur clic dans le widget avec touche CTRL
• ActionKPIS permettant de déterminer l'action sur clic dans le widget avec touche SHIFT

Tableau

• Titre du widget
• Titre de chaque colonne (1 à 8)
• Texte à afficher pour chaque colonne (1 à 8)
• Priorité de l'élément (couleur)
• ActionKPI permettant de déterminer l'action sur double-clic dans le widget
• ActionKPIC permettant de déterminer l'action sur clic dans le widget avec touche CTRL
• ActionKPIS permettant de déterminer l'action sur clic dans le widget avec touche SHIFT

CHAMPS ATTENDUS EN RETOUR DE LA REQUETE SQL
La requête retournera AUTANT de lignes qu'il y en aura à afficher dans le widget. Un widget liste en mode LISTE requiert uniquement les premières colonnes jusqu'à 'Conf', mais l'utilisation des actions avec touches nécessite alors de retourner les colonnes à ''.
Un widget liste en mode TABLEAU n'utilise pas la colonne 'Text' mais celles 'TitleColX' associée à 'TextColX' et 'AlignX'

Alignement
G ou L pour un alignement à gauche
D ou R pour un alignement à droite
C pour un alignement centré


GRAPHIQUES

• Type de graphique
• Titre de l'axe horizontal
• Titre de l'axe vertical
• Orientation du graphique (histogramme seulement)
• Palette de couleur à utiliser
• Afficher ou non la légende
• Valeur
• Libellé

CHAMPS ATTENDUS EN RETOUR DE LA REQUETE SQL
Il existe deux modes de fonctionnement, selon que la requête est en mesure de retourner plusieurs valeurs d'une même série ou non. Le choix du graphique impose le nombre de séries :

• Camembert : une seule série

• Histogramme ou courbe : plusieurs séries.

  Nom	Libellé	Nature
  ID	Identifiant non utilisé	Chaîne
  TypeGraph	Type de graphique	Chaîne 5
  HorizontalAxeTitle	Titre de l'axe horizontal	Chaîne 40
  VerticalAxeTitle	Titre de l'axez vertical	Chaîne 40
  Orientation	Orientation du graphique	Chaîne 1
  Palette	Nom de la palette de couleurs	Chaîne 20
  ShowLegend	Affichage de la légende	Entier 1
  Serie	Texte de la série	Chaîne 80
  Indice	Indice	Entier 2
  IndiceValue	Valeur pour l'indice	Décimal 12,3
  IndiceText	Texte pour l'indice	Chaîne 40
  V01Value	Valeur de la VALEUR1	Décimal 12,3
  V01Text	Texte de la VALEUR1	Chaîne 40
  …
  V20Value	Valeur de la VALEUR20	Décimal 12,3
  V20Text	Texte de la VALEUR20	Chaîne 40
  TranslateCol	Liste des numéros de colonnes à traduire séparés par ';' Chaîne 40	Chaîne 40

  
  
  Mode « 0 » de Graphique

• Ce mode utilise les champs V01VALUE+V01TEXT jusqu'à V20VALUE+V20TEXT pour chaque ligne résultante de la requête, c'est-à-dire que la requête peut retourner plusieurs valeurs de la série.
• Permet d'écrire une ou plusieurs requête (avec UNION) qui vont remplir les cellules de 1 à 20 pour la série.
• La détection du changement de série effectue la sauvegarde pour le graphique, donc les cellules peuvent être remplies par plusieurs requêtes successives. Les données doivent donc être traitées dans l'ordre des séries.

Exemple : une requête calcule V01 pour un état de départ qui tient compte du passé (par exemple un stock en début d'année) et l'union avec une seconde requête calculer V02 à V012 (par exemple les stocks mensuels).
Mode « 1 » de Graphique

• Ce mode utilise les champs INDICE+INDICEVALUE+INDICETEXT pour chaque ligne résultante de la requête.
• Passe par l'écriture de plusieurs requêtes (avec UNION) qui vont chacune indiquer une cellule individuelle.
• La détection du changement de série effectue la sauvegarde pour le graphique. Les données doivent donc être traitées dans l'ordre des séries.

Exemple : une requête qui nécessite un COUNT ou GROUP BY calcule une cellule à la fois
Options de graphique
Type :

• P pour camembert
• B pour histogramme
• L pour courbes
• Suivi de 0 ou 1 selon le « mode » donc par exemple B1 ou L0

Mode 0 ou 1 de graphique : illustration
Le widget requiert une suite de valeurs par série
S1 : V1 V2 V3 V4
S2 : V1 V2 V3 V4
La requête SQL sert à remplir les séries (sauf camembert qui n'en a qu'une) et les valeurs. Le mode 0 ou 1 change l'interprétation du résultat des requêtes.
Le mode 0 suppose que la requête puisse retourner toutes les valeurs d'une série en une fois. Les différentes séries sont obtenues par UNION entre les requêtes de chaque série
Requête 1 donne S1 : V1 V2 V3 V4
UNION
Requête 2 donne S2 : V1 V2 V3 V4
Le mode 1 permet de renseigner cellule par cellule par UNION des différentes requêtes. Les cellules ne sont pas forcément dans l'ordre.
Requête 1 donne S1 : Indice1 donc V1
UNION
Requête 2 donne S1 : Indice4 donc V4
UNION
Requête 3 donne S1 : Indice2 donc V2
UNION
Requête 4 donne S2 : Indice2 donc V2
Orientation (histogramme uniquement) :

• H pour horizontal
• V pour vertical

Affichage de légende

• 1 pour Oui
• 0 pour Non

Palette de couleurs Windows parmi (voir l'aide runtime) :
Artic, Autumn, Cold, Flower, Forest, Grayscale, Ground, Lilac, Natural, Pastel, Rainbow, Spring, Summer, Warm, Windows8

Vues SQL pour KPI

L'accès aux données au travers des vues SQL est simplifié.
Exemple : lecture du Code dossier, Référence, Désignation, Code nature produit, Libellé nature produit, Classe produit dans la table des ARTICLES

Requête SQL 'directe'
SELECT
ART.DOS AS DOSSIER
,ART.REF AS REFERENCE
,ART.DES AS DESIGNATION
,ART.PRODNAT AS NATUREPRODUIT
,NATURE_PRODUIT.LIB AS NATUREPRODUITLIBELLE
,LEFT(ART.PRODNAT,1) AS CLASSEPRODUIT
FROM ART
LEFT JOIN T000 AS T000 ON T000.DOS = '999 '
LEFT JOIN T036 AS NATURE_PRODUIT ON NATURE_PRODUIT.CEBIN = 36 AND ( NATURE_PRODUIT.DOS =
CASE WHEN T000.TABTYP_0036 = 2 THEN '999 ' ELSE ART.DOS END ) AND NATURE_PRODUIT.PRODNAT =
ART.PRODNAT
ORDER BY DOSSIER,REFERENCE

Requête SQL 'avec utilisation de la vue' (La jointure est déjà prévue)
SELECT
ARTICLE_V.DOSSIER,
ARTICLE_V.REFERENCE,
ARTICLE_V.DESIGNATION,
ARTICLE_V.NATUREPRODUIT,
ARTICLE_V.NATUREPRODUITLIBELLE,
ARTICLE_V.CLASSEPRODUIT
FROM ARTICLE_V
ORDER by DOSSIER,REFERENCE

Requête SQL 'avec utilisation de la vue et jointure' (la jointure n'est pas prévue)
SELECT
ARTICLE_V.DOSSIER,
ARTICLE_V.REFERENCE,
ARTICLE_V.DESIGNATION,
ARTICLE_V.NATUREPRODUIT,
NATURE_PRODUIT.LIBELLE AS NATUREPRODUITLIBELLE,
ARTICLE_V.CLASSEPRODUIT
FROM ARTICLE_V
LEFT JOIN TABLE_NATURE_PRODUIT_V AS NATURE_PRODUIT ON (ARTICLE_V.NATUREPRODUIT =
NATURE_PRODUIT.NATUREPRODUIT AND ARTICLE_V.DOSSIER = NATURE_PRODUIT.DOSC)
ORDER by DOSSIER,REFERENCE

Erreur IA de chargement de widget

Lorsque l'IA charge un widget en erreur en raison de son paramétrage, cela provoque un arrêt de l'IA. Pour corriger, il faut trouver le fichier de configuration de l'IA par utilisateur (NomUtilisateur.config) et le supprimer.
Ce fichier est stocké dans un dossier nommé 'ia' qui est lui-même stocké dans divalto/NOMENVIRONNEMENT.
Exemple : /divalto/erp212/demo.config

Astuces SQL

UNION
Permet le mélange du résultat de plusieurs requêtes successives. Dans ce cas les champs doivent être strictement dans le même ordre et du même type.
RTRIM
Enlève les espaces.
FORMAT(date,'dd/MM/yyyy')
Formate une date.
FORMAT(decimal, 'C', 'fr-fr')
Formate une valeur en montant €.
CONCAT(a,b,c)
Concatène les chaines a et b et c.
COALESCE(a,b,c)
Prend la première valeur trouvée dans l'ordre a puis b puis c.
CAST(champDate as date)
Force la conversion d'un champ Date en date SQL pour comparaison.
CASE WHEN condition1 THEN cas1 ELSE cas2 END
Test de condition.
YEAR(date)
Retourne l'année de la date.
MONTH(date)
Retourne le mois de la date.
RANK() OVER (ORDER BY X) as RANG ......ORDER BY RANG
Attribue un compteur de lignes du select.
dbo.PIECECONCAT(prefpino,pino)
Fonction de concaténation d'un préfixe de pièce avec le numéro de pièce.