Compart lance DocBridge® Communication Suite
Lancement sur le marché de DocBridge® Communication Suite : De nouvelles normes en matière de flexibilité et de technologie dans la gestion de la communication avec les clients.
Plus
DevBlog
Un onboarding plus rapide grâce aux dictionnaires de données (Data Dictionaries)
Thorsten Meudt |
TL;DR
Avec les nouveaux dictionnaires de données, DocBridge® Communication Suite simplifie considérablement la manière dont les données sont intégrées : Les sources externes les plus diverses rencontrent un modèle de données stable et uniforme. Qu'il s'agisse de simples configurations .dds et .ddm ou de transformations XSL à plusieurs niveaux dans le processus Gear, on voit ici comment des ensembles de données dynamiques peuvent être traités efficacement - et il y a là beaucoup de potentiel pour l'avenir !
Concept
Les dictionnaires de données ont été introduits en tant que MVP (Minimum Viable Product) dans la version Spring 2024 de DocBridge® Communication Suite et ont été améliorés depuis.
L'objectif principal des dictionnaires de données est de créer une couche d'abstraction entre des sources de données externes avec des structures de données différentes (et éventuellement variables, par exemple en raison d'une migration) et un modèle de données interne stable qui peut être utilisé au sein du DBCS par différents modèles et processus.
Chaque environnement DBCS peut contenir zéro, un ou plusieurs dictionnaires de données. Si vous préférez ne pas utiliser de dictionnaires de données, vous pouvez continuer à utiliser l'approche connue dans les versions précédentes de DocBridge® Impress, dans laquelle un « fichier de données xml » est directement attribué à chaque modèle, sans aucun mappage.
Quelles sont les ressources nécessaires pour configurer et utiliser les dictionnaires de données DBCS ?
Tout d'abord, vous devez créer un schéma de dictionnaire de données et le placer dans le Resource Director. Ce schéma décrit les champs que vous souhaitez gérer dans votre dictionnaire de données, leur attribue des noms et des valeurs de prévisualisation (pour Impress Designer) et contient des exemples d'enregistrements qui peuvent être utilisés dans le mode de prévisualisation d'Impress Designer ou même dans les workflows Gear lorsqu'il n'y a pas de connexion à la source de données en amont.
Data Dictionary Editor
Pour créer un schéma de dictionnaire de données, vous pouvez utiliser le confortable éditeur de dictionnaire de données. Pour ce faire, cliquez sur « + » dans Resource Director pour créer une nouvelle ressource, puis sélectionnez la tuile « Catalogues de données ».
Alternative : créer un schéma de dictionnaire de données directement au format XML
Vous pouvez également créer un schéma de dictionnaire de données sous forme de fichier XML et le télécharger dans Resource Director. Un schéma de dictionnaire de données simple pourrait se présenter comme suit :
<?xml version="1.0" encoding="UTF-8"?>
<DataDictionary
xmlns="http://www.compart.com/ns/data-dictionary/schema">
<Name>DD Name</Name>
<Title>Title of DataDictionary</Title>
<Description>This is the description of the DataDictionary</Description>
<DocumentMode mode="document" loop="/"/>
<DataSchema id="Root">
<DisplayName>Root</DisplayName>
<Content>
<Entry id="FirstName">
<DisplayName>FirstName</DisplayName>
<Preview>Marco</Preview>
</Entry>
<Entry id="LastName">
<DisplayName>LastName</DisplayName>
<Preview>Fabiani</Preview>
</Entry>
<Entry id="StreetName">
<DisplayName>StreetName</DisplayName>
<Preview>Mühlenstraße</Preview>
</Entry>
<Entry id="HouseNumber">
<DisplayName>HouseNumber</DisplayName>
<Preview>78</Preview>
</Entry>
<Entry id="ZipCode">
<DisplayName>ZipCode</DisplayName>
<Preview>10234</Preview>
</Entry>
<Entry id="City">
<DisplayName>City</DisplayName>
<Preview>Berlin</Preview>
</Entry>
<Entry id="Country">
<DisplayName>Country</DisplayName>
<Preview>Deutschland</Preview>
</Entry>
<Entry id="PolicyNumber">
<DisplayName>PolicyNumber</DisplayName>
<Preview>K 123-852369/P</Preview>
</Entry>
<Entry id="PolicyName">
<DisplayName>PolicyName</DisplayName>
<Preview>Kraftfahrtversicherung Klassik Privat</Preview>
</Entry>
<Entry id="InvoiceDate">
<DisplayName>InvoiceDate</DisplayName>
<Preview>2024-06-05</Preview>
</Entry>
</Content>
</DataSchema>
<SampleSets default="SampleSet-1">
<SampleSet id="SampleSet-1">
<DisplayName>SampleSet-1</DisplayName>
<Data>
<Root>
<FirstName>Marco</FirstName>
<LastName>Fabiani</LastName>
<StreetName>Mühlenstraße</StreetName>
<HouseNumber>78</HouseNumber>
<ZipCode>10234</ZipCode>
<City>Berlin</City>
<Country>Deutschland</Country>
<PolicyNumber>K 123-852369/P</PolicyNumber>
<PolicyName>Kraftfahrtversicherung Klassik Privat</PolicyName>
<InvoiceDate>2024-06-05</InvoiceDate>
</Root>
</Data>
</SampleSet>
</SampleSets>
</DataDictionary>Ci-dessous, vous pouvez voir la source de données externe que nous souhaitons utiliser pour l'exemple. Il s'agit de données XML qui pourraient par exemple être introduites dans notre processus Gear via REST ou MQ :
<?xml version="1.0" encoding="UTF-8"?>
<Policyholders>
<Policyholder gender="female" preferredLang="de">
<LastName>Schneider</LastName>
<FirstName>Anna</FirstName>
<Birthday>1985-07-22</Birthday>
<Address>
<ZipCode>80331</ZipCode>
<City>München</City>
<StreetName>Leopoldstraße</StreetName>
<HouseNumber>23</HouseNumber>
<State>Bayern</State>
<Country>Deutschland</Country>
</Address>
<ContactDetails>
<email>anna.schneider@example.com</email>
<phone>01761123456</phone>
</ContactDetails>
<PolicyNumber premium="yes">M 456-789012/A</PolicyNumber>
<PolicyName>Haftpflichtversicherung</PolicyName>
<InvoiceDate>15.11.2023</InvoiceDate>
</Policyholder>
<Policyholder gender="male" preferredLang="en">
<LastName>Fabiani</LastName>
<FirstName>Marco</FirstName>
<Birthday>1961-01-30</Birthday>
<Address>
<ZipCode>10234</ZipCode>
<City>Berlin</City>
<StreetName>Mühlenstraße</StreetName>
<HouseNumber>78</HouseNumber>
<State>Berlin</State>
<Country>Deutschland</Country>
</Address>
<ContactDetails>
<email>fabiani.marco@liberi.it</email>
<phone>0171444965</phone>
</ContactDetails>
<PolicyNumber premium="yes">K 123-852369/P</PolicyNumber>
<PolicyName>Kraftfahrtversicherung Klassik Privat</PolicyName>
<InvoiceDate>24.10.2023</InvoiceDate>
</Policyholder>
<Policyholder gender="male" preferredLang="en">
<LastName>Smith</LastName>
<FirstName>John</FirstName>
<Birthday>1970-03-15</Birthday>
<Address>
<ZipCode>10001</ZipCode>
<City>New York</City>
<StreetName>5th Avenue</StreetName>
<HouseNumber>742</HouseNumber>
<State>NY</State>
<Country>USA</Country>
</Address>
<ContactDetails>
<email>john.smith@example.com</email>
<phone>2125551234</phone>
</ContactDetails>
<PolicyNumber premium="no">N 789-123456/B</PolicyNumber>
<PolicyName>Health Insurance Basic</PolicyName>
<InvoiceDate>01.12.2023</InvoiceDate>
</Policyholder>
</Policyholders>Data Dictionary Mapping
Nous voulons maintenant créer un fichier de mappage qui transfère les données de cette structure source vers le dictionnaire de données que nous avons créé précédemment. Actuellement, vous devez créer ce fichier .ddm manuellement, mais cela est également assez simple - à l'avenir, cette étape sera également facilitée par un éditeur pratique. Placez le fichier .ddm dans le Resource Director afin de pouvoir l'utiliser dans votre processus Gear. Notez que nos données sources contiennent plusieurs enregistrements ; pour une meilleure vue d'ensemble, le mappage des données s'effectue au niveau des enregistrements individuels.
Dans un fichier .ddm (Data Dictionary Mapping), on définit comment certains champs d'une source de données externe doivent être transférés dans la structure du dictionnaire de données. Dans l'exemple illustré, cela signifie concrètement :
Définition du schéma :
L'élément <Schema> avec l'ID « Root » sert de point d'entrée. Dans ce schéma sont définis tous les champs nécessaires (Entries) qui doivent être représentés dans le dictionnaire de données.
Les éléments Entry :
Chaque élément <Entry> possède une ID unique qui correspond au champ correspondant dans le dictionnaire de données (par exemple « PreferredLanguage », « FirstName », « LastName », etc.). Ces identifiants sont essentiels pour que le système sache comment attribuer et traiter les données par la suite.
Zone source avec XPath :
Au sein de chaque élément <Entry>, <Source> permet de définir d'où doivent provenir les valeurs dans le XML externe. Cela se fait par l'expression <XPath>.
Par exemple :
<XPath>/Policyholder/@preferredLang</XPath>
Cette expression indique que la valeur est lue dans l'attribut @preferredLang de la balise <Policyholder>. La structure de données externe est ainsi mappée sur le champ souhaité dans le dictionnaire de données. Pour « InvoiceDate », une petite conversion est même effectuée via la fonction XPath concat, par exemple pour adapter un format de date.
Résultat :
Le mapping relie donc chaque champ individuel (Entry) du dictionnaire de données à la section correspondante dans les données XML externes. Lors de l'exécution ultérieure du processus (p. ex. dans un workflow Gear), le mappage est effectué à l'aide de ce fichier .ddm et tous les champs sont correctement repris dans le dictionnaire de données.
<?xml version="1.0" encoding="UTF-8"?>
<DataMapping xmlns="http://www.compart.com/ns/data-dictionary/mapping" version="1.0">
<Schema id="Root">
<Entry id="PreferredLanguage">
<Source>
<XPath>/Policyholder/@preferredLang</XPath>
</Source>
</Entry>
<Entry id="Gender">
<Source>
<XPath>/Policyholder/@gender</XPath>
</Source>
</Entry>
<Entry id="FirstName">
<Source>
<XPath>/Policyholder/FirstName</XPath>
</Source>
</Entry>
<Entry id="LastName">
<Source>
<XPath>/Policyholder/LastName</XPath>
</Source>
</Entry>
<Entry id="StreetName">
<Source>
<XPath>/Policyholder/Address/StreetName</XPath>
</Source>
</Entry>
<Entry id="HouseNumber">
<Source>
<XPath>/Policyholder/Address/HouseNumber</XPath>
</Source>
</Entry>
<Entry id="ZipCode">
<Source>
<XPath>/Policyholder/Address/ZipCode</XPath>
</Source>
</Entry>
<Entry id="City">
<Source>
<XPath>/Policyholder/Address/City</XPath>
</Source>
</Entry>
<Entry id="PolicyName">
<Source>
<XPath>/Policyholder/PolicyName</XPath>
</Source>
</Entry>
<Entry id="PolicyNumber">
<Source>
<XPath>/Policyholder/PolicyNumber</XPath>
</Source>
</Entry>
<Entry id="InvoiceDate">
<Source>
<XPath>concat(substring(/Policyholder/InvoiceDate, 7, 4), '-',
substring(/Policyholder/InvoiceDate, 4, 2), '-',
substring(/Policyholder/InvoiceDate, 1, 2))</XPath>
</Source>
</Entry>
</Schema>
</DataMapping>Comme vous pouvez le constater, nous affectons ici les valeurs des données sources aux différentes entrées de notre dictionnaire de données, par exemple l'attribut @preferredLang est affecté à l'unité du dictionnaire de données « PreferredLanguage ».
Vous pouvez également constater que nous pouvons facilement effectuer des transformations de données standard via XSLT, par exemple pour relier des chaînes de caractères entre elles, comme le montrent les lignes 57-59. Vous trouverez les fonctions XSLT et xPath supportées par Compart dans la documentation de DocBridge Communication Suite.
La dernière ressource dont vous avez besoin pour utiliser les dictionnaires de données est la feuille de style XSL pour le mappage des données, qui est livrée avec DocBridge® Communication Suite. En règle générale, vous ne devez pas y apporter de modifications.
Mise en œuvre des dictionnaires de données dans un processus Gear
Nous voulons maintenant tout rassembler et créer un processus Gear qui mappe nos données sources dans la structure du dictionnaire de données et génère en sortie un fichier de collecte PDF.
Comme plusieurs enregistrements doivent être traités, nous devons mapper les données séparément pour chaque enregistrement. C'est pourquoi, après avoir lu les données XML entrantes dans un DOM, nous utilisons le DOM Iterator Worklet. Ensuite, nous utilisons le XSLT Transformer Worklet pour transférer les données sources pour chaque enregistrement dans la structure du dictionnaire de données.
Ce processus de prétraitement est de préférence emballé dans une worklet composée, qui possède une broche d'entrée ByteReader et une broche de sortie DOM :
Après avoir assemblé les worklet, nous devons configurer l'itérateur DOM et définir l'expression XPath sur laquelle itérer afin de créer un DOM distinct pour chaque ensemble de données. Cliquez avec le bouton droit de la souris sur le worklet DOM Iterator et sélectionnez « Configuration du worklet ». En utilisant les données d'exemple présentées ci-dessus, définissez la valeur comme suit :
Ensuite, ouvrez la configuration pour le XSLT Transformer Worklet. Ici, vous devez définir le paramètre « XSLT URI » sur l'URI sous lequel vous avez déposé la feuille de style XSL de data-mapping, ainsi que le paramètre XSL. Pour le paramètre XSL, vous placez la clé sur « datasource » et le contenu sur l'URI sous laquelle vous avez déposé la configuration de mapping. Voir l'exemple :
Pour finir, nous pouvons créer notre worklet principal en reliant le worklet composé de prétraitement en amont à un worklet Impress et à un PDF Writer, comme illustré ci-dessous. Veillez à définir le paramètre « Impress Template configuration » sur l'URI sous lequel vous avez déposé un modèle Impress approprié pour votre dictionnaire de données (Data Dictionaries) :
Si vous souhaitez obtenir un seul fichier PDF de sortie « par lots » au lieu de PDF individuels (car nous avons utilisé l'itérateur DOM pour diviser les données d'entrée par lots en enregistrements individuels), vous devez définir le déclencheur d'entrée « only » sur « DomSeparator » dans la configuration de PDF Writer (clic droit sur le worklet PDF Writer) pour les « séparateurs ».
Conclusion
L'implémentation des dictionnaires de données dans DocBridge® Communication Suite couvre l'essentiel des fonctionnalités permettant d'abstraire différentes sources de données externes d'un modèle de données interne unifié, qui peut être utilisé rapidement et efficacement dans différents modèles et processus.
