Installatiehandleiding v3.1.3.0 1. Installeer de Windows service m.b.v. het installatiebestand XMLSplitterSetup.msi. 2. Configureer de service door de correcte waarden in te vullen binnen het bestand Configuration.xml. Dit bestand is te vinden in de installatiedirectorie van de XML Splitter. Standaard is deze directory ingesteld op: C:\Program Files\Circle Software\. Voorbeeld Configuration.xml : <configurations logfile="" XSLTScriptingSupported="true" logonlyiffailed="false"> <redirector scanfolder="" notprocessedfolder="" timerinterval=""> <redirect xpath="" configuration=""/> </redirector> <csvconverter name="" priority="0" csvcolumndelimiter=";" csvcolumnquote=" " saveasseparatexmls="false" firstrowcontainsheader="true" timestampingenabled="false" trimcolumns="true" removequotes="true" columnnameastag="false" skipemptytags="true"> <scanfolder></scanfolder> <processedfolder></processedfolder> <outputfolder></outputfolder> <timerinterval></timerinterval> <outputencoding></outputencoding> </csvconverter> <webserviceplugin name="" priority="0" operationcwp="" url="" timestampingenabled="false"> <scanfolder></scanfolder> <processedfolder></processedfolder> <notprocessedfolder></notprocessedfolder> <timerinterval></timerinterval> </webserviceplugin> <configuration name="" priority="0" timestampingenabled="false"> <scanfolder stylesheet=""></scanfolder> <processedfolder></processedfolder> <outputfolder stylesheet=""></outputfolder> <timerinterval></timerinterval> <splitatnode></splitatnode> <outputencoding></outputencoding> <substitutechar></substitutechar> </configuration> </configurations> scanfolder Dit is de directory waarin gekeken wordt naar de aangeboden XML bestanden. Indien het attribuut stylesheet gevuld is, wordt voor het splitsen de betreffende stylesheet gebruikt. <scanfolder stylesheet="c:\scan_input.xsl">c:\scan</scanfolder> Vanaf versie 1.2.1 kan men in dit attribuut punt-komma gescheiden meerdere stylesheets definieren. Deze worden in de volgorde uitgevoerd, zoals deze ingevoerd zijn. <scanfolder stylesheet="c:\inp1.xsl;c:\inp2.xsl">c:\scan</scanfolder> Zo wordt eerst inp1.xsl uitgevoerd, vervolgens inp2.xsl en dan wordt de output hiervan gesplit. 1 / 11
processedfolder outputfolder Dit is de directory waarin het gesplitste XML bestand na verwerking wordt opgeslagen. Indien men een gesplitst bestand na verwerking wil verwijderen, dan DELETE=YES als directory opgeven. Dit is de directory waarin de separate XML bestanden worden opgeslagen. Indien het attribuut stylesheet gevuld is, wordt na het splitsen de betreffende stylesheet gebruikt. Bijvoorbeeld: <outputfolder stylesheet="c:\scan_output.xsl">c:\output</outputfolder> logfile timerinterval splitatnode outputencoding Dit is het bestand waarin de resultaten van het splitsen worden weggeschreven. Dit is het interval waarmee in de scanfolder wordt gekeken of nieuwe XML bestanden zijn toegevoegd. Dit interval wordt uitgedrukt in milliseconden. Daarnaast is het mogelijk om één keer per dag de bestanden uit de scanfolder te verwerken, dan wordt dit opgegeven door ONCE=hh:mm:ss. Dit is het type node waarop gesplitst wordt. Indien opgegeven worden de gesplitste bestanden weggeschreven in de opgegeven encoding, anders wordt de encoding van het bronbestand overgenomen. Mogelijke input waarden: ASCII CURRENT_SYSTEM_ANSI ISO-8859-1 UTF-16 UTF-16BE UTF-32 UTF-7 UTF-8 substitutechar Indien opgegeven worden binnen de gesplitste bestanden de karakters vervangen zoals aangegeven in de subxxx regels. In onderstaand voorbeeld wordt karaktercode 138 tijdens het splitsen vervangen door karaktercode 352. Daarnaast wordt karaktercode 154 tijdens het splitsen vervangen door karaktercode 353. <substitutechar> <sub001>138;352</sub001> <sub002>154;353</sub002> </substitutechar> Deze lijst is vrij uit te bereiden. Door meerdere <configuration> secties te configureren kunnen dus meerdere kanalen gedefinieerd worden. 2 / 11
Vanaf versie 2.0.0.0 kunnen ook prioriteiten voor de kanalen ingesteld worden. Daarnaast kan aangegeven worden of de output met een timestamp geprefixt dient te worden, dit i.v.m. periodiek aangeleverde XML s met telkens dezelfde naam. <configuration name="" priority="0" timestampingenabled="false"> Vanaf versie 2.2.0.0 kunnen ook redirects ingesteld worden. Aan de redirector kunnen meerdere redirects worden opgegeven. <redirector scanfolder="" notprocessedfolder="" timerinterval=""> Per redirect dient een XPath expressie meegegeven te worden. Bij de eerste expressie die resultaat geeft zal het xml document naar de scanfolder van de bijbehorende configuratie verplaatst worden. Indien de redirector geen match vindt, plaatst deze het bestand in de notprocessedfolder. Vanaf versie 3.0.0.0 kunnen ook CSV converters ingesteld worden. <csvconverter name="" priority="0" csvcolumndelimiter=";" csvcolumnquote=" " saveasseparatexmls="false" firstrowcontainsheader="true" timestampingenabled="false" trimcolumns="true" removequotes="true" columnnameastag="false" skipemptytags="true"> csvcolumndelimiter csvcolumnquote saveasseparatexmls firstrowcontainsheader timestampingenabled trimcolumns removequotes columnnameastag uppercasename Indien opgegeven worden de kolommen gesplitst o.b.v. deze delimiter, indien niet opgegeven wordt ',' gehanteerd. Gebruik de waarde 'TAB' indien men een bestand heeft dat o.b.v. tabs geïnterpreteerd dient te worden. Indien opgegeven worden de kolommen gecontroleerd of deze tussen quotes staan, indien niet opgegeven wordt '"' gehanteerd. Indien opgegeven worden de regels als één XML bestand of per regel weggeschreven, indien niet opgegeven wordt 'false' gehanteerd. Indien opgegeven wordt de eerste regel als header geïnterpreteerd, indien niet opgegeven wordt 'true' gehanteerd. Indien opgegeven worden de verwerkte en aangemaakte bestanden geprefixed met een timestamp, indien niet opgegeven wordt 'false' gehanteerd. Indien opgegeven worden de kolomwaarden getrimmed, indien niet opgegeven wordt 'true' gehanteerd. Indien opgegeven worden de kolomwaarden die tussen " staan zonder quotes weggeschreven, indien niet opgegeven wordt 'true' gehanteerd. Indien opgegeven worden de nodes o.b.v. de headernamen aangemaakt, anders wordt de header als attribute in de standaard tag opgenomen, indien niet opgegeven wordt 'false' gehanteerd. Indien opgegeven worden de kolomnamen met hoofdletters genoteerd, anders wordt de header zoals in het bronbestand overgenomen, indien niet opgegeven wordt 'false' gehanteerd. 3 / 11
skipemptytags Indien opgegeven worden lege nodes niet weggeschreven, indien niet opgegeven wordt 'true' gehanteerd. Door meerdere < csvconverter> secties te configureren kunnen dus meerdere kanalen gedefinieerd worden. Zie bijlage 2 voor voorbeelden omtrent conversies van CSV naar XML bestanden(en). De overige nodes binnen deze configuratie zijn hetzelfde als voor de standaard configuratie, buiten het feit dat geen stylesheets op de kanalen geplaatst kunnen worden. Vanaf versie 3.1.0.0 kunnen ook Webservice transacties ingesteld worden. < webserviceplugin name="" priority="0" operationcwp="" url="" timestampingenabled="false"> operationcwp url Dit is de operatie die binnen de Common Webservice Plugin is gedefinieerd. Dit is de URL waar het bericht naar toe gestuurd dient te worden. Door meerdere < webserviceplugin> secties te configureren kunnen dus meerdere kanalen gedefinieerd worden. De overige nodes binnen deze configuratie zijn hetzelfde als voor de standaard configuratie, buiten het feit dat geen stylesheets op de kanalen geplaatst kunnen worden. Aanvullende informatie omtrent het gebruik van de Common Webservice Plugin: Omdat binnen deze actie de Common Webservice Plugin wordt gebruikt, dient voor de verdere configuratie de handleiding van deze plugin gehanteerd te worden. Deze handleiding staat in de map CommonWS_Support binnen de installatie map van de XML Splitter. De XMLSplitter logt alleen de foutmelding van de Common Webservice Plugin. Voor gedetailleerde informatie dient naar het Webservice reply bericht van de Common Webservice Plugin gekeken te worden. Als de Common Webservice Plugin nog niet geïnstalleerd is op de betreffende server, zal de plugin handmatig geregistreerd moeten worden, deze procedure staat in de handleiding van de plugin vermeldt. De versie van de plugin die vanaf XMLSplitter v3.1.3.0 wordt meegeleverd is v2.2000.0.0. 4 / 11
Start vervolgens de service via de Service Manager van Windows. 3. Controleer na het starten van de service of het tekstbestandje Configuration.Err is aangemaakt in de installatiedirectorie van de XML Splitter. Indien dit bestandje werd aangemaakt, is iets niet of niet goed ingesteld in de configuratie XML. Als dit bestandje dus niet werd aangemaakt is alles in orde. Voorbeeld Configuration.Err : ---------------------------- Configuration Errors ---------------------------- File : C:\Program Files\Circle Software\\Configuration.xml Date : 9-7-2008 10:22:22 Error(s) : 5 # Het element 'scanfolder' is niet of incorrect gedefinieerd. # Het element 'processedfolder' is niet of incorrect gedefinieerd. # Het element 'outputfolder' is niet of incorrect gedefinieerd. # Het element 'logfile' is niet of incorrect gedefinieerd. # Het element 'splitatnode' is niet gedefinieerd. De configuratie XML bijwerken indien een foutmelding is opgetreden en de service herstarten. Indien men wijzigingen aanbrengt in de configuratie XML zal de Windows service een restart nodig hebben, want enkel bij het starten van de service wordt de configuratie XML ingelezen. Voor meer info: JRN Vanaf versie 2.0.0.0 kunnen bepaalde functies binnen stylesheets gebruikt worden, zogenaamde Extension Objects. Voor een overzicht van de te gebruiken functies zie bijlage 1. Vanaf versie 2.1.0.0 staat de ondersteuning van scripting in stylesheets standaard aan. <configurations logfile="" XSLTScriptingSupported="true"> Indien deze waarde op false staat, worden de acties binnen stylesheets beperkt. Zo worden scripts binnen een stylesheet geblokkeerd en is het niet mogelijk om de document() functie te gebruiken. Microsoft raadt aan om scripting alleen in een vertrouwde omgeving te activeren. 5 / 11
*** Nieuw *** Naast de Windows service is vanaf versie 1.0.2.0 ook een handmatige tool aanwezig. Deze tool is te vinden in de installatiedirectorie, onder de naam csgxmlsplittergui.exe. De overeenkomende naam, met de additie Service i.p.v. GUI is de Windows service. Deze kan alleen via de service manager gestart worden. Deze handmatige tool heeft twee opties, aan de rechterkant te selecteren: Manuele configuratie: Configuratie op basis van de Configuration.xml : Bij de ConfigXML -configuratie kan men enkel het bestand opgeven dat gesplitst dient te worden. De overige settings worden uit de XML ingelezen. Hiermee kan men de Windows service handmatig simuleren. 6 / 11
Voor het uitproberen van andere settings, kan men de Manueel -configuratie gebruiken, hierbij kan men alleen het gesplitste bestand niet laten verplaatsen. Doordat men vaker verschillende dingen wil testen, hoeft niet telkens het splitsbestand teruggezet te worden via de Windows verkenner. Ook als men voor een eenmalige import actie een initieel XML bestand moet uitsplitsen, dan kan deze handmatige tool gebruikt worden. Vanaf versie 1.2.0 werkt onderstaande tip Tip: Door dubbel te klikken op de textbox van Log bestand wordt het huidige log bestand getoond: *** Commandline optie /FILE=<pad naar bestand> *** Daarnaast kan men via de commandline een splitsbestand meegeven. csgxmlsplittergui.exe /file= C:\Documents and Settings\Verseon\test.xml /config= Scans Dan wordt automatisch de ConfigXML modus gestart en het bestand test.xml wordt uitgesplitst volgens de configuratie Scans Hierbij zal geen scherm getoond worden en is enkel in de logfile terug te vinden of alles correct verliep. Deze optie kan gebruikt worden als men geen gebruik wil maken van de Windows service, maar toch via een Scheduled Task binnen Windows een taak wil plannen om een bepaald XML bestand uit te splitsen. Een mogelijke uitbreiding van de XML Splitter is een /FOLDER=<map> commandline optie om d.m.v. Scheduled Tasks mappen uit te lezen. De huidige Windows service voorziet in de optie ONCE= als timerinterval, maar hierbij is het enkel mogelijk om eenmaal per dag een map uit te lezen. Voor meer info: JRN 7 / 11
Bijlage 1. Extension Objects Door de stylesheet tag uit te breiden met onderstaande namespaces, kan gebruik worden gemaakt van voorgeprogrammeerde functies. <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/xsl/transform" xmlns:msxsl="urn:schemas-microsoft-com:xslt" xmlns:csg="urn:xsltcustomfunctions" > Zo kun je bijvoorbeeld een variabele vullen o.b.v. een functie: <xsl:variable name="currentdate" select="csg:currentdate()"/> Zie volgende pagina voor informatie voor gebruik van de XSLTCustomFunctionsParser binnen oxygen, zodat stylesheets met custom functions handig ontwikkeld kunnen worden. Huidige functies: Functie Resultaat Vanaf CurrentDate() Geeft huidige datum in UTC formaat terug. Bijv. 2010-04-08T00:00:00 2.0.0.0 Now() Geeft huidige tijdstip in UTC formaat terug. Bijv. 2010-04-08T08:14:47 2.0.0.0 Telt de opgegeven dagen op bij de AddDays(string date, double days) betreffende datum 2.0.0.0 Vergelijkt twee datums en geeft de volgende waarde terug: CompareDates(string startdate, 1 = startdate groter dan enddate string enddate) 0 = startdate gelijk aan enddate 2.0.0.0-1 = startdate kleiner dan enddate -99 = fout opgetreden LowerCase(string text) Geeft de opgegeven tekst in kleine 2.0.1.0 letters terug UpperCase(string text) Geeft de opgegeven tekst in hoofdletters 2.0.1.0 terug IsNumber(string check) Geeft een boolean terug met indicatie 2.1.0.0 IsEmpty(string check) Geeft een boolean terug met indicatie 2.1.1.0 IsNotEmpty(string check) Geeft een boolean terug met indicatie 2.1.1.0 CompareTextCaseInsensitive(string Geeft een boolean terug met indicatie 2.1.1.0 texta, string textb) CompareTextCaseSensitive(string texta, string textb) Trim(string text) LPad(string text, int length, string padchar) RPad(string text, int length, string padchar) GetDirectory(string path) GetFileName(string path) Geeft een boolean terug met indicatie 2.1.1.0 Geeft de opgegeven tekst getrimmed terug 2.1.1.0 Left padding van tekst 3.0.0.0 Right padding van tekst 3.0.0.0 Geeft de directory binnen een volledig pad terug Geeft de bestandsnaam binnen een volledig pad terug 3.0.0.0 3.0.0.0 8 / 11
GetFileExtension(string path) GetFileNameAndExtension(string path) Now_UTC_Z() Convert_Date_To_UTC_Z(string date) Geeft de bestandsextensie binnen een volledig pad terug Geeft de bestandsnaam en -extensie binnen een volledig pad terug Geeft huidige tijdstip in UTC_Z formaat terug. Bijv. 2010-04-08T07:14:47Z Converteert een tijdstip naar UTC_Z formaat. Bijv. 2010-04-08T08:14:47 wordt in onze tijdzone 2010-04-08T07:14:47Z 3.0.0.0 3.0.0.0 3.1.2.0 3.1.2.0 Zie volgende pagina voor instellen van de XSLTCustomFunctionsParser binnen oxygen. 9 / 11
Voor gebruik van de XSLTCustomFunctionsParser binnen oxygen dient een eigen engine te worden opgegeven: Via het menu: Opties -> Voorkeuren -> XML -> XSLT-FO-XQuery -> Eigen Engines Commandoregel: "C:\Program Files\Circle Software\\XSLTCustomFunctionsParser.exe" /XML=${xmlu} /XSLT=${xslu} /SAVETO=${out} Maak vervolgens een scenario aan, waarbij als Transformer de XSLTCustomFunctionsParser geselecteerd wordt. Dit scenario kan nu gebruikt worden voor stylesheets met custom functions. 10 / 11
Bijlage 2. Voorbeeld conversie CSV naar XML bestand(en) CSV Bestand test.csv : NAAM;ACHTERNAAM Janssen;Piet Pietersen;Jan CSV Converter settings: saveasseparatexmls columnnameastag = true = true <Rows filename="test.csv" filepath="c:\test.csv"> <NAAM>Janssen</NAAM> <ACHTERNAAM>Piet</ACHTERNAAM> </Rows> saveasseparatexmls columnnameastag = false = true <Rows filename="test.csv" filepath="c:\test.csv"> <NAAM>Janssen</NAAM> <ACHTERNAAM>Piet</ACHTERNAAM> <NAAM>Pietersen</NAAM> <ACHTERNAAM>Jan</ACHTERNAAM> </Rows> saveasseparatexmls columnnameastag = true = false <Rows filename="test.csv" filepath="c:\test.csv"> <Col name="naam">janssen</col> <Col name="achternaam">piet</col> </Rows> saveasseparatexmls columnnameastag = false = false <Rows filename="test.csv" filepath="c:\test.csv"> <Col name="naam">janssen</col> <Col name="achternaam">piet</col> <Col name="naam">pietersen</col> <Col name="achternaam">jan</col> </Rows> 11 / 11