Handleiding. Versie Laatste wijziging: Ontwikkeld door iadvise. Web: Mail:

Handleiding

Versie 01.02 Laatste wijziging: 14-04-2014 Ontwikkeld door iAdvise

Web: http://www.doxxy.eu Mail: [email protected] Twitter: @doxxyNews

iAdvise

Doxxy

I NHOUDSTABEL 1

2

3

4

5

Inleiding ........................................................................................................................... 4 1.1

Woord vooraf ............................................................................................................ 4

1.2

Wat mag je verwachten van Doxxy? ........................................................................... 5

1.3

Wat is reeds mogelijk in Doxxy? ................................................................................. 5

Installatie ......................................................................................................................... 6 2.1

Software vereisten ..................................................................................................... 6

2.2

Installatie................................................................................................................... 6

Op verkenning in Doxxy .................................................................................................... 8 3.1

Folders....................................................................................................................... 9

3.2

Documenten .............................................................................................................11

Een eerste rapport ...........................................................................................................13 4.1

Folder en document aanmaken (Start) .......................................................................13

4.2

Gegevens selecteren (Wat?) ......................................................................................15

4.3

Templates maken (Hoe?) ...........................................................................................19

4.4

Preview opvragen (Preview) ......................................................................................24

4.5

Rapport oproepen (Run)............................................................................................26

Uitgewerkt voorbeeld ......................................................................................................30 5.1

Situering ...................................................................................................................30

5.2

Uitwerking ................................................................................................................32

5.2.1 Folder en document aanmaken (Start) ....................................................................... 32 5.2.2 Gegevens selecteren (Wat?) ....................................................................................... 32 5.2.2.1 Orders ................................................................................................................... 32 5.2.2.2 Customers ............................................................................................................. 35 5.2.2.3 Items (List) ............................................................................................................ 37 5.2.2.4 Items (table) ......................................................................................................... 38 5.2.2.5 Product available .................................................................................................. 40 Inhoudstabel Doxxy - Handleiding Versie: 01.02

2 - 69

iAdvise

Doxxy

5.2.3 Template aanmaken (Hoe?) ........................................................................................ 41 5.2.3.1 De brief ................................................................................................................. 42 5.2.3.2 De bijlage .............................................................................................................. 44 5.2.4 Extra functionaliteiten ................................................................................................ 46 5.2.4.1 PL/SQL Statements ............................................................................................... 46 5.2.4.2 Validatie van de template.................................................................................... 47 5.2.4.3 Meta Data Fiche ................................................................................................... 48 5.2.4.4 Visualisatie van de template ................................................................................ 50 6

Tips & tricks .....................................................................................................................52

7

Deployment ....................................................................................................................54 7.1

Exporteren ................................................................................................................54

7.1.1 7.1.2 7.2 8

Export van een document ........................................................................................... 54 Export van meerdere documenten ............................................................................. 55

Importeren van documenten .....................................................................................56

SYSAdmin / Admin mogelijkheden ...................................................................................57 8.1

Userbeheer ...............................................................................................................58

8.2

Logging .....................................................................................................................60

8.2.1 8.2.2

Log configurations ....................................................................................................... 60 Log messages .............................................................................................................. 61

8.3

Beheren van licenties ................................................................................................62

8.4

Beheren van Synoniemen ..........................................................................................62

APPENDIX Installatie..............................................................................................................64 Inleiding..............................................................................................................................64 Installatiestappen binnen APEX ...........................................................................................65

Inhoudstabel Doxxy - Handleiding Versie: 01.02

3 - 69

iAdvise

Doxxy

1 INLEIDING 1.1 W OORD VOORAF Op dit moment bestaan er nauwelijks (goedkope) producten voor het genereren van Microsoft Worddocumenten op basis van gegevens uit de Oracle databank. Tools die hiervoor toch in aanmerking zouden kunnen komen, zijn vaak duur, vereisen een ingewikkelde installatieprocedure of zijn moeilijk in gebruik. Dankzij de Doxxy tool, een oplossing geschreven in puur PL/SQL, is het vanaf nu wel mogelijk om met een laag budget en op een eenvoudige manier documenten te genereren vanuit de Oracle databank. Brondocumenten (templates) kunnen door de gebruiker opgemaakt en opgeladen worden en hieruit kunnen op een eenvoudige en snelle manier Word-documenten gegenereerd worden waarin gegevens vanuit de Oracle databank worden samengevoegd. De front-end voor het beheren van je metadata, zoals het selecteren van je data of het opladen van de templates, is gemaakt in Oracle Application Express (APEX). Het is een eenvoudige tool waarmee je, zonder een omslachtige installatieprocedure, onmiddellijk aan de slag kunt. Bovendien zijn er toch al heel wat reporting functionaliteiten in opgenomen, aangevuld met interessante nieuwe features in Doxxy 01.02. Standaard is het output formaat een DOCX-bestand. Sinds versie 01.02 is het nu ook mogelijk een PDF-bestand te laten aanmaken. We wensen je alvast veel plezier met Doxxy!

Inleiding Doxxy - Handleiding Versie: 01.02

4 - 69

iAdvise

Doxxy

1.2 W AT MAG JE VERWACHTEN VAN D OXXY ? -

-

Eenvoudige tool waarmee je heel snel aan de slag kunt gaan Volledig gebruik van alle Microsoft Word opties, zoals verschillende lettertypes, vet, onderstrepen, lijsten, tabellen, afbeeldingen, … Scheiding van templates en data. Templates kunnen eventueel aangeleverd worden door de gebruiker, zonder dat deze over Oracle-kennis hoeft te beschikken. De data kan los hiervan worden samengesteld door een Oracle-ontwikkelaar De layout van de documenten wordt bepaald door de opmaak van de template in Microsoft Word. De gebruiker heeft dus enkel kennis van deze tekstverwerker nodig Microsoft Word tabellen worden ondersteund en kunnen worden gevuld met gegevens uit de Oracle databank Opsommingslijsten, zowel de ongenummerde als de genummerde, worden ondersteund en kunnen worden gevuld met gegevens uit de Oracle-databank Dynamische kop-en voetteksten worden ondersteund Afbeeldingen en grafieken in de template worden ondersteund …

1.3 W AT IS REEDS MOGELIJK IN D OXXY ? -

Input van gegevens uit de Oracle-databank via SQL-statements Vastleggen van input parameters Hergebruik van kolommen en parameters in andere SQL-statements Het uitvoeren van een stuk PL/SQL code bij het begin of het einde van het rapport Geneste master-detail structuren Gegevens weergeven volgens verschillende layout mogelijkheden: tekst (paragrafen), tabellen en lijsten Conditioneel weergeven van teksten en gegevens Conditionele opmaak van teksten en gegevens Weergeven van afbeeldingen: zowel vast in de template als afbeeldingen uit de databank Opladen van verschillende templates (o.a. nuttig indien je je rapport naar verschillende talen wil genereren) Genereren naar DOCX Via een extra licentie-optie, kan ook een PDF-bestand als output worden gegenereerd

Inleiding Doxxy - Handleiding Versie: 01.02

5 - 69

iAdvise

Doxxy

2 INSTALLATIE 2.1 S OFTWARE VEREISTEN Databank APEX

Oracle 10.2 of hoger APEX 4.x of hoger

2.2 I NSTALLATIE Doxxy 01.02 komt als een export bestand van een Packaged Application voor APEX. Dit bestand bevat dus 1) zowel de APEX UI als 2) alle database objecten als “supporting objects”. Het installatieproces bestaat uit de volgende stappen 1. Maak een specifiek Doxxy database schema aan 2. Maak een workspace in APEX aan en koppel hieronder het Doxxy database schema 3. Meld aan op deze workspace en importeer hierin de toegezonden APEX export file, inclusief de “Supporting Objects”. Meer informatie betreffende de derde stap kan u vinden in de Appendix.

Opmerkingen 

Standaard verwijst de IMAGE_PREFIX eigenschap naar /i/. Gelieve deze aan te passen indien nodig naar jouw omgeving.



De installatie van Doxxy komt met één standaard gebruiker: sysadmin / sysadmin. Gelieve dit paswoord aan te passen via de applicatie naar de eigen specifieke vereisten.



De “Supporting Objects”, waarvan sprake is in stap 3 van de installatie, bevatten alle nodige Doxxy objecten + de PL/SQL engine.

Installatie Doxxy - Handleiding Versie: 01.02

6 - 69

iAdvise

Doxxy

Voorbeeld script voor het aanmaken van een specifiek Doxxy schema REM change password + tablespace name to your requirements CREATE USER dg4o_0102 IDENTIFIED BY <my_password> DEFAULT TABLESPACE users TEMPORARY TABLESPACE temp QUOTA UNLIMITED ON users; GRANT GRANT GRANT GRANT GRANT GRANT GRANT GRANT GRANT GRANT GRANT GRANT

CREATE SESSION TO dg4o_0102; CREATE SEQUENCE TO dg4o_0102; CREATE SYNONYM TO dg4o_0102; CREATE PUBLIC SYNONYM TO dg4o_0102; CREATE ANY CONTEXT TO dg4o_0102; CREATE PROCEDURE TO dg4o_0102; DROP PUBLIC SYNONYM TO dg4o_0102; CREATE TYPE TO dg4o_0102; CREATE ANY DIRECTORY TO dg4o_0102; CREATE TRIGGER TO dg4o_0102; CREATE VIEW TO dg4o_0102; CREATE TABLE TO dg4o_0102;

Installatie Doxxy - Handleiding Versie: 01.02

7 - 69

iAdvise

Doxxy

3 OP VERKENNING IN D OXXY Om op verkenning te gaan in Doxxy, moet Doxxy eerst opgestart worden in een internetbrowser. Surf naar de juiste APEX url en meld je aan met je gebruikersnaam en wachtwoord.

Na succesvol aanmelden, kom je op de “Home”-pagina terecht. Afhankelijk van de rechten die je gebruiker toegekend heeft gekregen en de folders waartoe je toegang hebt, krijg je onderstaand scherm te zien.

Je kan steeds terugkeren naar deze startpagina via de broodkruimelnavigatie bovenaan, net onder de zwarte balk, of door op het Doxxy logo te klikken in de linker bovenhoek.

Op verkenning in Doxxy Doxxy - Handleiding Versie: 01.02

8 - 69

iAdvise

Doxxy

3.1 F OLDERS Links wordt via een handige interactieve boomstructuur een overzicht getoond van al de folders, subfolders, documenten en document details waartoe je toegang hebt. Rechts worden de details getoond van het aangeklikte tree-item. Op de volgende afbeelding zie je een overzicht van je folders.

Folders aanmaken kan je doen via de knop “Create Folder”. Kies een goede naam, vul eventueel wat uitleg in en kies indien nodig een bovenliggende folder waaronder deze nieuwe folder zal vallen. Klik vervolgens op “Create”.


9 - 69

iAdvise

Doxxy

Een folder openen, doe je door op de gewenste folder te klikken in de boomstructuur links. Op de onderstaande afbeelding zie je dat de folder “DOXXY” geopend is. Deze folder bevat op zijn beurt een aantal subfolders, nl. “APEX”, “DEMO” en “SYSTEM”. Onder de folder “DEMO” is o.a. het demorapport “Order Confirmation” aangemaakt, die we verder in deze handleiding zullen bespreken.

Je kan de eigenschappen van je folder bekijken en bewerken (aanpassen, subfolder aanmaken, importeren, exporteren, verwijderen) via de knop “Actions”.


10 - 69

iAdvise

Doxxy

3.2 D OCUMENTEN Documenten kunnen op alle folderniveaus aangemaakt worden. Indien je in de boomstructuur op een folder met documenten klikt, krijg je rechts de details van deze documenten te zien. Via de broodkruimelnavigatie kan je altijd terug uit je folders navigeren.

Documenten aanmaken kan je doen via de knop “Create Document” of via het “+”-icoontje dat verschijnt als je over een folder in de boomstructuur hoovert. Kies een geschikte naam voor je document, vul eventueel wat uitleg in en kies de juiste folder waartoe dit nieuwe document zal behoren. Klik vervolgens op “Create”.

Merk op dat de begin- en eindtag kunnen ingesteld worden per document. In dit geval zijn dit vierkante haken “[” en “]”, maar deze kunnen indien gewenst aangepast worden. We zullen deze tags nodig hebben tijdens het aanmaken van de templates.


11 - 69

iAdvise

Doxxy

Een document openen, doe je door op het gewenste document te klikken in de boomstructuur links. Op de onderstaande afbeelding zie je dat het document “Order Confirmation” geopend is. Een document bestaat uit één of meerdere SQL statements, één of meerdere PL/SQL statements, één of meerdere templates en eventueel input parameters. Op de onderstaande afbeelding is het demorapport “Order Confirmation” geopend. Zowel in de boomstructuur links, als in het detailoverzicht rechts kan je gemakkelijk navigeren tussen de SQL statements, PL/SQL statements, de templates en de parameters.

Je kan de eigenschappen van je document bekijken en bewerken (aanpassen, verwijderen, verplaatsen, exporteren, meta data rapport opvragen, template visualiseren, …) via de knop “Actions”. Een preview (DOCX-rapport) opvragen van je werk, doe je via de knop “Preview” of via het handige oog-icoontje dat verschijnt als je over een document in de boomstructuur hoovert.


12 - 69

iAdvise

Doxxy

4 E EN EERSTE RAPPORT Bij het aanmaken van een rapport doorloop je steeds enkele stappen. Eventueel worden deze meerdere keren achter elkaar herhaald, totdat je het gewenste resultaat bekomen hebt.

4

Stap Start Data = Wat? Layout = Hoe? Preview

5

Run

1 2 3

Omschrijving Aanmaken van gewenste folder en document Selecteren van de databank gegevens die je in je rapport wil weergeven Vastleggen op welke manier je de gegevens wil tonen in je rapport via een template Preview opvragen van je rapport om te zien of het aan je wensen voldoet Oproepen van je rapport vanuit je eigen toepassing

Waar? In de Doxxy tool In de Doxxy tool In je eigen Wordtemplate In de Doxxy tool In je eigen toepassing

In de volgende paragrafen wordt beknopt omschreven hoe je deze verschillende stappen kan uitvoeren met de Doxxy tool. Binnen Doxxy zijn naast het “Wat?” en het “Hoe?” nog twee extra verfijningen van het aanmaken van een rapport mogelijk: nl. het definiëren van één of meerdere parameters en het koppelen van PL/SQL logica voor of na het uitvoeren van een rapport. Deze extra mogelijkheden komen aan bod in het volgende hoofdstuk met een volledig uitgewerkt voorbeeld.

4.1 F OLDER EN DOCUMENT AANMAKEN (S TART ) Voordat je begint, creëer je best een geschikte folder voor je test-rapporten of navigeer je naar de gewenste folder. Voor deze handleiding gebruiken we de folder “My Documents”.

Een eerste rapport Doxxy - Handleiding Versie: 01.02

13 - 69

iAdvise

Doxxy

Deze folder is aanvankelijk leeg.

Creëer vervolgens het gewenste document waaronder je alle metadata, zoals SELECT-statements, PL/SQL statements, templates en parameters, voor je rapport zal beheren. Klik hiervoor rechtsboven op de knop “Create Document” of klik op het “+”-icoontje dat verschijnt als je over de folder hoovert waaronder je het document wenst aan te maken.

Kies een gepaste naam voor je document en vul eventueel een beknopte beschrijving in. Klik vervolgens rechtsonder op de knop “Create”.


14 - 69

iAdvise

Doxxy

Nadat het document is aangemaakt, zien we deze onder de folder verschijnen waar deze is aangemaakt. Als we nu op de documentnaam klikken, kunnen we dit document echt vorm gaan geven door “SQL Statements” toe te voegen, “Templates” op te laden en, indien nodig, een “PL/SQL proces” toe te voegen of input “Parameters” te definiëren. Merk op dat je verschillende mogelijkheden hebt om tussen de verschillende gegevens te navigeren: dit kan zowel via de boomstructuur links, als via de tabs in het detailscherm rechts.

4.2 G EGEVENS SELECTEREN (W AT ?) In deze stap bepaal je welke gegevens je wil tonen in je rapport. Dit doe je door de gegevens te selecteren via één of meerdere SELECT-statements.

Eerst en vooral hebben we gegevens nodig om in ons rapport weer te geven. In dit voorbeeld zullen we een eenvoudig overzicht tonen van alle geplaatste bestellingen uit de tabel DEMO_ORDERS. Klik op de knop “Create SQL” in de “SQL”-tab en vul de velden in.


15 - 69

iAdvise

Doxxy

Name Kies een duidelijke, unieke naam voor je SQL-statement. Sequence Een volgnummer voor het SQL-statement; dit bepaalt de volgorde van de SQL-statements in de visualisatie in de Doxxy UI en in de “processing” door de Doxxy-engine. Description Optioneel kan er een beschrijving toegevoegd worden.


16 - 69

iAdvise

Doxxy

Parent SQL statement In het geval je een master-detail structuur wil weergeven, kan je hier je master SQL-statement aanduiden. De keuzelijst wordt automatisch gevuld met alle reeds aangemaakte SQL-statements. SQL Statement Hierin schrijf je je statement dat de gewenste gegevens ophaalt uit de databank om later in je rapport te tonen. Usage in Document Via dit keuzelijstje maak je duidelijk op welke manier je de gegevens zal weergeven in je rapport. Je hebt hierbij keuze uit vijf soorten layouts: - Table: in een tabel - List: in een genummerde of ongenummerde opsommingslijst - Paragraph: in een paragraaf, als gewone losstaande tekst (in vorige versie van Doxxy heette dit Global document) - Page Break: in een paragraaf, waarbij na elk record van het SELECT statement steeds een page break wordt toegevoegd - Page Reset: in een paragraaf, waarbij na elk record van het SELECT statement steeds een page break wordt toegevoegd en eventuele pagina nummers terug worden gereset naar 1 Recordset Code Kies een duidelijke, unieke code voor je SQL-statement. Deze code zal je in je template moeten gebruiken om naar je statement te verwijzen. Tip: gebruik hiervoor hoofdletters, zo vallen ze op in je document tussen de gewone teksten. Document Area Via dit keuzelijstje kan je aanduiden in welke area in je rapport je de gegevens zal plaatsen: - Body of a document - Header of a document - Footer of a document Parse SQL Het is steeds mogelijk om na het ingeven van een SQL-statement de syntax te controleren door te klikken op de knop “Parse SQL”. Afhankelijk van of dit geslaagd is, wordt een gepaste mededeling zichtbaar.


17 - 69

iAdvise

Doxxy

Copy from SQL SQL-statements kunnen gekopieerd worden vanuit alle documenten uit alle folders waartoe je toegang hebt.

Klik tenstlotte op de knop “Create” om het aanmaken van je SQL-statement te bevestigen. Als je nu terug gaat naar de informatiepagina betreffende het aangemaakte document, zien we dit SQLstatement staan in het tabblad “SQL”.

Heb je nog meer gegevens nodig, dan kan je deze selecteren via extra SQL-statements. Je kan deze “Create SQL” stap zo vaak als je wil herhalen, totdat je alle gegevens verzameld hebt. Voor het wijzigen van een reeds geschreven SQL-statement, klik je op de naam van dit statement. In de volgende stap zullen we een template maken en deze hier opladen. Een eerste rapport Doxxy - Handleiding Versie: 01.02

18 - 69

iAdvise

Doxxy

4.3 T EMPLATES MAKEN (H OE ?) In deze stap leg je de layout van je rapport vast. Je bepaalt hoe je rapport er precies moet uitzien en dit kan je heel eenvoudig door je rapport uit te ‘tekenen’ in een Word-document (=template). In deze Word-template mag je alle functionaliteiten gebruiken die Microsoft Word je aanbiedt. Op plaatsen waar je gegevens uit de databank wil inlassen zet je een “code”-woord. Deze code-woorden, kortweg codes, mag je op verschillende plaatsen gebruiken: 1. In een paragraaf als gewone tekst 2. In een opsommingslijst 3. In een tabel De codes kunnen gebruikt worden voor verschillende doeleinden. Hiervoor is telkens een bepaalde syntax te volgen: 1. Starten van een set gegevens afkomstig uit een SQL-statement: [BEGIN:MY_RECORDSET_CODE] 2. Afsluiten van een set gegevens afkomstig uit een SQL-statement: [END:MY_RECORDSET_CODE] 3. Ophalen van gegevens uit een SQL-statement: [MY_COLUMN_NAME] 4. Conditioneel weergeven van gegevens: [IF:MY_CHECK] … inhoud indien MY_CHECK = 1 … [ELSE:MY_CHECK] … inhoud indien MY_CHECK = 0 … (niet verplicht te noteren, indien leeg) [ENDIF:MY_CHECK] Hierbij is MY_CHECK een kolom uit een SQL-statement die 1 of 0 teruggeeft. 5. Weergeven van afbeeldingen uit de databank: [IMG:MY_BLOB_COLUMN] Hierbij is MY_BLOB_COLUMN een kolom uit een SQL-statement die een BLOB teruggeeft die de afbeelding bevat. Het teken voor de begin- en eindtag kunnen via de “Edit Document Info” ingevuld worden en staan standaard ingesteld op linker en rechter vierkante haakjes.


19 - 69

iAdvise

Doxxy

Als je in een volgende stap je rapport gaat genereren, zal je rapport er op precies dezelfde manier uitzien, zoals je dat bepaald hebt in je Word-template. De codes zijn hierbij vervangen door de gewenste gegevens uit je SELECT-statements. Heb je de codes in een tabel geplaatst dan zal Doxxy automatisch het juiste aantal rijen tonen volgens het aantal records dat het bijhorende SELECT-statement teruggeeft. Staat er een code in een opsommingslijst, dan zal deze lijst eveneens het juiste aantal items bevatten volgens het bijhorende SELECT-statement. Deze paragraaf legt uit hoe je je template maakt. Meer gedetailleerde informatie over het conditioneel weergeven van gegevens en het tonen van afbeeldingen in je rapport, vind je in het uitgewerkte voorbeeld in het volgende hoofdstuk. Om je template te maken, open je Microsoft Word. Maak je document op zoals je wil dat je rapport er zal moeten uitzien: titels, tabellen, lijsten, kop- en voetteksten, afbeeldingen, … Wil je gegevens uit een SQL-statement inlassen, dan heb je drie weergave-mogelijkheden: paragraaf, opsommingslijst of tabel. Enkele concrete voorbeelden: Paragraaf [BEGIN:ORDERS]Customer [CUST_NAME] made an order on [ORDER_DATE]. He had to pay €[ORDER_TOTAL] for the ordered products.[END:ORDERS] Opsommingslijst  [BEGIN:ORDERS][CUST_NAME] - [ORDER_DATE] - €[ORDER_TOTAL][END:ORDERS] Tabel Customer Name [BEGIN:ORDERS] [CUST_NAME]

Order Date [ORDER_DATE]

Order Total (€) [ORDER_TOTAL] [END:ORDERS]


20 - 69

iAdvise

Doxxy

Belangrijke opmerkingen 1. Het is steeds verplicht om het begin en het einde van een statement aan te duiden via de BEGIN- en END-tags, ongeacht de weergave. 2. De gebruikte codes in de BEGIN- en END-tags verwijzen naar de Recordset Codes uit de SQLstatements. Voor een betere leesbaarheid wordt aangeraden om deze codes steeds in hoofdletters te noteren, bv. [BEGIN:ORDERS]. 3. De gebruikte codes voor het verwijzen naar de kolomnamen in de SQL-statements kunnen eveneens best in hoofdletters worden genoteerd, bv. [CUST_NAME], [ORDER_DATE] en [ORDER_TOTAL]. Een voorbeeld van een mogelijke template in Word:

Sla je template op en geef het hierbij een betekenisvolle naam, bv. orders_template.docx. Ga vervolgens terug naar je document in de Doxxy-webtoepassing. Navigeer naar de juiste folder en selecteer het document waarvoor je een template wilt toevoegen (dezelfde als waar je daarnet een SQLstatement hebt voor geschreven).


21 - 69

iAdvise

Doxxy

Onder de tab “Templates” kan je je templates opladen. Op dit moment is het lijstje van opgeladen templates nog leeg.

Klik op de knop “Create Template” van het tabblad “Templates” of klik op het “+”-icoontje dat verschijnt als je in de opengeklikte boomstructuur over “Templates” hoovert, om de gemaakte template toe te voegen. Vul de velden in.

Template Name Kies een duidelijke, unieke naam voor je document template. Upload New Template Kies hier het eerder opgeslagen Word-document die als template gaat dienen. De naam hiervan wordt ook de filename. Een eerste rapport Doxxy - Handleiding Versie: 01.02

22 - 69

iAdvise

Doxxy

Template Format Bestandstype van de template. Op dit moment kan je enkel DOCX aanduiden. Description Hierin kan je informatie invullen betreffende je template. Klik op de knop “Create” om het aanmaken van je document template te bevestigen. Je ziet nu dat je template is opgeladen.

Je kan meerdere templates opladen voor een document. Bij het genereren van je rapport kies je dan volgens welke template de report generator je gegevens moet weergeven. Dit kan handig zijn indien je bv. een nederlandstalige en een franstalige versie van eenzelfde rapport wil maken. In dat geval maak je twee templates: ééntje in het Nederlands en ééntje in het Frans. Om meerdere templates toe te voegen, gelieve bovenstaande stap te herhalen. Wil je een bestaande template bekijken of de template aanpassen, klik dan op de naam van de template. Het is dan mogelijk deze aangepaste versie opnieuw te uploaden.


23 - 69

iAdvise

Doxxy

4.4 P REVIEW OPVRAGEN (P REVIEW ) Nadat je de gewenste data hebt geselecteerd en je templates opgeladen zijn in de Doxxy tool, kan je je rapport testen door een preview op te vragen. Ga in Doxxy naar het overzicht van je aangemaakte documenten. Selecteer het juiste document en klik vervolgens op de “Preview”-knop in de rechterbovenhoek om het rapport te genereren.

Ook handig is de mogelijkheid om een preview op te vragen via de het “oog”-icoontje dat verschijnt als je over het gewenste document in de boomstructuur hoovert.

In beide gevallen kom je op het “Generate Preview” scherm terecht. Na selectie van de juiste template kan het rapport gedownload worden. Hier kies je op basis van welke template Doxxy je rapport moet genereren. Het keuzelijstje wordt automatisch gevuld met al je opgeladen templates. Indien je gebruik hebt gemaakt van parameters, dan kan je de waarden eveneens hier invullen. Parameters worden in het uitgewerkte voorbeeld in het volgende hoofdstuk behandeld.


24 - 69

iAdvise

Doxxy

Klik vervolgens op de knop “Download Preview”. Als alles succesvol verloopt, wordt er een rapport gegenereerd dat je kan opslaan en openen.

Het Output format staat standaard op “DOCX”. Als je licentie ook de PDF-optie bevat, dan kan je ook “PDF” als output formaat kiezen. Het resultaat kan je bekijken door de gedownloade preview te openen.

Je kan voor een bepaald document de stappen 2 tot en met 4 zo vaak herhalen als je wil, totdat je rapport het gewenste resultaat heeft. Een eerste rapport Doxxy - Handleiding Versie: 01.02

25 - 69

iAdvise

Doxxy

4.5 R APPORT OPROEPEN (R UN ) Wanneer je klaar bent met je rapport in Doxxy, zal je deze willen oproepen vanuit je eigen toepassing. Hiervoor is er een aanroepfunctie voorzien. Via een aantal parameters geef je de nodige gegevens en input parameters door. Als resultaat krijg je je gegenereerde document in de vorm van een BLOB. De aanroepfunctie bestaat onder een basis (eenvoudigere, maar beperktere) en een generieke (iets meer ingewikkelde, maar complete) vorm. Beide zijn terug te vinden in de package BL$DG4O_INTERFACE onder het database schema waarin Doxxy werd geïnstalleerd.

Beperkte vorm FUNCTION generate_document( p_document IN VARCHAR2 ,p_document_template_name IN VARCHAR2 ,p_bind_variable_name_1 IN VARCHAR2 DEFAULT NULL ,p_bind_variable_text_1 IN VARCHAR2 DEFAULT NULL ,p_bind_variable_name_2 IN VARCHAR2 DEFAULT NULL ,p_bind_variable_text_2 IN VARCHAR2 DEFAULT NULL ,p_bind_variable_name_3 IN VARCHAR2 DEFAULT NULL ,p_bind_variable_number_3 IN NUMBER DEFAULT NULL ,p_bind_variable_name_4 IN VARCHAR2 DEFAULT NULL ,p_bind_variable_number_4 IN NUMBER DEFAULT NULL ,p_bind_variable_name_5 IN VARCHAR2 DEFAULT NULL ,p_bind_variable_date_5 IN DATE DEFAULT NULL ,p_bind_variable_name_6 IN VARCHAR2 DEFAULT NULL ,p_bind_variable_date_6 IN DATE DEFAULT NULL ,p_application_key IN VARCHAR2 DEFAULT NULL ,p_user_id IN dg4o_users.username%TYPE DEFAULT NULL ,p_format IN VARCHAR2 DEFAULT 'DOCX') RETURN BLOB;

De parameters vul je als volgt op: 

Via de parameter “p_document” geef je je gewenste document mee. Zowel de naam van het document als het volledige pad moeten opgegeven worden en zijn hoofdlettergevoelig. Voor ons voorbeeldrapport wordt dit: p_document => ‘/MY_FOLDER/My Documents/Orders overview’



Via de parameter “p_document_template_name” geef je je gewenste template mee. Voor ons voorbeeldrapport wordt dit: p_document_template_name => ‘Orders Template’


26 - 69

iAdvise

Doxxy



Vervolgens heb je mogelijkheid om twee parameters in te vullen van datatype VARCHAR2, twee parameters van datatype NUMBER en twee parameters van datatype DATE. Dit kan een beperking opleveren, indien je rapport meerdere parameters vereist. In dat geval maak je gebruik van de generieke aanroepfunctie (zie verder). In ons voorbeeld rapport zijn geen parameters gedefinieerd. Veronderstel echter dat we een parameter P_ORDER_ID zouden aangemaakt hebben, die een numerieke waarde als input verwacht, dan kan je deze parameter als volgt invullen: p_bind_variable_name_3 => 'P_ORDER_ID', p_bind_variable_number_3 => 1 (voor order id 1)



Via de parameter “p_application_key” geef je de application key mee, indien deze voor het document vereist is. Meer informatie over application keys vind je onder het hoofdstuk “Admin mogelijkheden”. Voor ons voorbeeldrapport is geen application key vereist.



Via de parameter “p_user_id” kan je de username meegeven. Deze parameter is voorzien voor verdere ontwikkeling in een volgende release en is hier nog niet van toepassing.



Via de parameter “p_format” kan je het gewenste output-formaat meegeven; in de TRIAL-versie is sowieso enkel ‘DOCX’ mogelijk. Dit is trouwens de default waarde. Als je een licentie hebt voor de PDF-optie, kan je hier ook ‘PDF’ meegeven.

Generieke vorm FUNCTION generate_document( p_document IN VARCHAR2 ,p_document_template_name IN VARCHAR2 ,p_bind_variables IN bind_variables_t ,p_application_key IN VARCHAR2 DEFAULT NULL ,p_user_id IN dg4o_users.username%TYPE DEFAULT NULL ,p_format IN VARCHAR2 DEFAULT 'DOCX') RETURN BLOB

De parameters vul je als volgt op: 

Via de parameter “p_document” geef je je gewenste document mee. Zowel de naam van het document als het volledige pad moeten opgegeven worden en zijn hoofdlettergevoelig. Voor ons voorbeeldrapport wordt dit: p_document => ‘/MY_FOLDER/My Documents/Orders overview’



Via de parameter “p_document_template_name” geef je je gewenste template mee. Voor ons voorbeeldrapport wordt dit: p_document_template_name => ‘Orders Template’


27 - 69

iAdvise

Doxxy



Vervolgens heb je i.p.v. een reeks van parameters slecht één record type parameter waarmee je alle input gegevens kan doorgeven. In ons voorbeeld rapport zijn geen parameters gedefinieerd. Veronderstel echter dat we een parameter P_ORDER_ID zouden aangemaakt hebben, die een numerieke waarde als input verwacht, dan kan je deze parameter als volgt invullen: p_bind_variables => l_bind_variables Waarbij je l_bind_variables vooraf dient in te vullen: l_bind_variables('P_ORDER_ID').number_value := 1; (voor order id 1)



De parameter “p_application_key”, “p_user_id” en “p_format” in de generieke vorm hebben dezelfde betekenis als deze parameters in de beperkte vorm.

Voorbeeld Om de functies te kunnen gebruiken in je eigen applicatie heb je een GRANT nodig op de package waartoe deze aanroepfuncties behoren, nl. de package BL$DG4O_INTERFACE. Een nuttige tip is ook een (al dan niet publiek) synoniem hiervoor aan te maken, bv. BL$DG4O_INTERFACE. Het genereren van je document kan je vervolgens laten gebeuren door onderstaande procedure in je toepassing uit te voeren (deze maakt gebruik van de generieke vorm van de aanroepfunctie). DECLARE l_bind_variables BL$DG4O_INTERFACE.bind_variables_t; l_doc BLOB; BEGIN l_bind_variables('P_ORDER_ID').number_value := 1; l_doc := BL$DG4O_INTERFACE.generate_document (p_document => '/MY_FOLDER/My Documents/Orders overview' ,p_document_template_name => 'Orders Template' ,p_bind_variables => l_bind_variables ,p_application_key => '' ,p_user_id => '' ,p_format => 'DOCX'); END;

Deze procedure levert een BLOB op, waarin je gegenereerde DOCX-document zit. Hiermee kan je verder in de toepassing aan de slag (downloaden, preview, printen, …).

Tip Via het “Generate Preview” scherm kan je deze PL/SQL code laten genereren door gebruik te maken van de knop “Show API Call”. Deze code kan je kopiëren en inlassen in je eigen applicatie.


28 - 69

iAdvise

Doxxy


29 - 69

iAdvise

Doxxy

5 U ITGEWERKT VOORBEELD 5.1 S ITUERING In dit hoofdstuk wordt een volledig uitgewerkt voorbeeld getoond dat gebruikt maakt van de DEMOtabellen die ook voor de Sample Application in APEX gebruikt worden.

Het voorbeeldrapport is een “Orderbevestiging”. Het toont een brief ter bevestiging van een geplaatste bestelling. Als bijlage bij de brief wordt er een lijst afdrukt met alle bestelde artikels. Je kan het rapport opvragen voor één bepaalde bestelling of voor alle bestellingen samen. Dit laatste resulteert in één brief per bestelling, allemaal achter elkaar samengebundeld in één Word-document.

Uitgewerkt voorbeeld Doxxy - Handleiding Versie: 01.02

30 - 69

iAdvise

Doxxy


31 - 69

iAdvise

Doxxy

5.2 U ITWERKING Het voorbeeldrapport “Order Confirmation” ziet er in Doxxy als volgt uit.

Deze paragraaf legt uit hoe we tot dit document zijn gekomen.

5.2.1 F OLDER EN DOCUMENT AANMAKEN (S TART ) Maak een nieuwe folder aan of navigeer naar de gewenste folder. Creëer onder deze folder een nieuw document met de naam “Order Confirmation”.

5.2.2 G EGEVENS SELECTEREN (W AT ?) Voor dit rapport hebben we gegevens uit verschillende tabellen nodig. Deze moeten geselecteerd worden via de juiste SQL-statements.

5.2.2.1 O RDERS Uiteraard hebben we de gegevens van de bestellingen zelf nodig. Deze bevinden zich in de tabel DEMO_ORDERS.


32 - 69

iAdvise

Doxxy

We willen de mogelijkheid inbouwen om: -

ofwel één brief voor een bestelling naar keuze af te drukken ofwel alle brieven voor alle bestellingen na elkaar af te drukken

Hiervoor hebben we een parameter nodig, nl. P_ORDER_ID. Om deze parameter te kunnen gebruiken in het SQL-statement, moeten we deze eerst aanmaken. Parameters kunnen aangemaakt worden via de tab “Parameters”.

Parameters kunnen we in het SQL-statement vervolgens aanroepen via de dubbelepunt-notatie van de “Bind Variable Name”, bv. :P_ORDER_ID.


33 - 69

iAdvise

Doxxy

Klik op de “SQL”-tab of op “SQL Statements” in de boomstructuur om een nieuw SQL-statement aan te maken. Voeg de nodige WHERE-clause toe om de parameter te controleren. Het SQL-statement met de naam “Orders” ziet er als volgt uit: SELECT o.order_id, TO_CHAR(o.order_timestamp, 'fmDD month YYYY', 'nls_date_language=american') order_timestamp, TRIM(TO_CHAR(o.order_total, '999G999D00')) order_total FROM demo_orders o WHERE (o.order_id = :P_ORDER_ID OR :P_ORDER_ID IS NULL)

De kolom ORDER_TIMESTAMP wordt gebruikt om de brief te dateren. De kolom ORDER_TOTAL wordt tweemaal in de brief afgedrukt. Merk op dat ook de kolom ORDER_ID wordt geselecteerd (dit is niet hezelfde als P_ORDER_ID). De kolom ORDER_ID zal als link gebruikt worden tussen de verschillende statements. Dit statement is het master-statement van het rapport. Het heeft zelf dus geen parent. Merk op dat er een “Parameters”-overzichtje rechts van het SQL-statement staat. Via dit “Parameters” kadertje is het eveneens mogelijk om parameters aan te maken of aan te passen. Wil je een parameter inlassen in een SQL-statement, dan kan je die zelf toevoegen via de dubbelepuntnotatie. Nog eenvoudiger kan dit door je cursor op de gewenste plaats in het statement te zetten en vervolgens op de naam van de parameter te klikken. Automatisch verschijnt de gekozen parameter met de juiste notatie in het SQL-statement. Indien de parameter op een correcte manier in het SQL-statement is opgenomen, zal de parameter in het overzichtje lichtjes in het blauw aangeduid staan. De parameter krijgt bovendien een groen vinkje indien alles correct is opgeslagen. Via “Usage in Document” duiden we de gewenste weergave aan, in dit geval “Page Break”. Dit betekent eigenlijk hetzelfde als “Paragraph” (aka “Global Document” in de vorige versie van Doxxy), maar dan met de extra functionaliteit dat er voor ieder nieuw order, telkens een impliciete page break zal toegevoegd worden. Op die manier verschijnt elk nieuw order automatisch op een nieuwe pagina. Als “Recordset Code” kiezen we “ORDERS”. De gegevens uit dit statement zullen getoond worden in de “Body of a document”. Bewaar je SQL-statement door op de knop “Create” te klikken. Als je al deze acties op de juiste manier hebt doorgevoerd, zou je het volgende resultaat moeten bekomen:


34 - 69

iAdvise

Doxxy

5.2.2.2 C USTOMERS De orderbevestiging wordt in de rechter bovenhoek geadresseerd aan de klant. Om de klantgegevens te kunnen afdrukken, moeten we deze selecteren uit de tabel DEMO_CUSTOMERS. Uiteraard willen we per brief enkel de klantgegevens zien van de klant die die bepaalde bestelling (ORDER_ID uit het vorige SQL-statement) heeft geplaatst waarvoor we de brief afdrukken. Hiervoor voegen we een WHERE-clausule toe aan het statement van de customers, nl. WHERE order_id = :ORDER_ID. Het SQL-statement met de naam “Customers” ziet er als volgt uit: SELECT c.cust_first_name, c.cust_first_name || ' ' || c.cust_last_name cust_name, c.cust_street_address1 || DECODE(c.cust_street_address2, NULL, NULL, ', ' || c.cust_street_address1) cust_street, c.cust_city || ', ' || c.cust_state || ' ' || c.cust_postal_code cust_city FROM demo_orders o JOIN demo_customers c ON o.customer_id = c.customer_id WHERE o.order_id = :ORDER_ID

De orders zijn in dit geval dus de “masters”, terwijl de customer-gegevens de “details” zijn van een bepaald order. Als “Parent SQL Statement” vullen we daarom het SQL-statement “Orders” in. Door het parent-statement in te vullen, krijg je rechts een overzichtje “Link Variables” te zien met alle kolommen uit dit parent-statement. Deze kolommen kunnen gebruikt worden om het detail-statement met het parent-statement te koppelen of te “binden”, het zijn m.a.w. de mogelijke te linken kolommen.


35 - 69

iAdvise

Doxxy

Indien je het parent-statement “Orders” correct hebt aangemaakt, zal de kolom ORDER_ID tussen de “Link Variables” staan. Het refereren naar de link variabele, gebeurt opnieuw via de dubbelepuntnotatie. Als ook dit correct gebeurd is, zal de link variabele in het overzichtje lichtjes in het blauw aangeduid staan. (Een groen vinkje verschijnt indien de link opgeslagen is.) Via “Usage in Document” duiden we de gewenste weergave aan, in dit geval “Paragraph”. Als “Recordset Code” kiezen we “CUSTOMERS”. De gegevens uit dit statement zullen getoond worden in de “Body of a document”. Bewaar je SQL-statement door op de knop “Create” te klikken. Als je al deze acties op de juiste manier hebt doorgevoerd, zou je het volgende resultaat moeten bekomen:


36 - 69

iAdvise

Doxxy

Merk ook op dat in de boomstructuur links je eveneens de master-detail structuur gevisualiseerd ziet tussen de verschillende queries.

5.2.2.3 I TEMS (L IST ) De items worden in dit rapport tweemaal afgedrukt en dit telkens in een andere weergave. In de brief worden de bestelde items weergegeven in een lijst. In de bijlage op het tweede blad worden de items getoond in een tabeloverzicht. Voor de lijst hebben we slechts twee kolommen nodig, nl. de naam van het product en de prijs. Bovendien willen we ook hier ook enkel die bestelde items voor de bestelling die we net aan het afdrukken zijn. Dit laatste doen we opnieuw door een WHERE-clausule toe te voegen, nl. WHERE order_id = :ORDER_ID, met ORDER_ID de kolom uit het parent SQL-statement “Orders”. Het SQL-statement met de naam “Items” ziet er als volgt uit: SELECT p.product_name, TRIM(TO_CHAR(i.unit_price * i.quantity, '999G999D00')) total_price FROM demo_order_items i JOIN demo_product_info p ON i.product_id = p.product_id WHERE i.order_id = :ORDER_ID ORDER BY p.product_name

Als “Parent SQL” vullen we het SQL-statement “Orders” in. Via “Usage in Document” duiden we de gewenste weergave aan, in dit geval “List”. Als “Recordset Code” kiezen we “ITEMS_LIST”. De gegevens uit dit statement zullen getoond worden in de “Body of a document”. Tenslotte kijken we na of de gebruikte link variabele ORDER_ID lichtjes blauw geaccentueerd staat. Bewaar je SQL-statement door op de knop “Create” te klikken.


37 - 69

iAdvise

Doxxy

Als je al deze acties op de juiste manier hebt doorgevoerd, zou je het volgende resultaat moeten bekomen:

5.2.2.4 I TEMS ( TABLE ) Eigenlijk hebben we in dit rapport tweemaal bijna dezelfde gegevens nodig. Deze gegevens hoef je dan ook slechts één keer te selecteren via eenzelfde SQL-statement. Dit SQL-statement is analoog aan het SQL-statement voor “Items (list)”. We hebben enkel wat extra kolommen nodig, waaronder een BLOB-kolom voor de afbeelding van het product. We kunnen het statement met de naam “Items” dus gewoon uitbreiden met de nodige extra kolommen. Het SQL-statement met de naam “Items” ziet er nu als volgt uit: SELECT p.product_name, p.product_description, TRIM(TO_CHAR(i.unit_price, '999G999D00')) unit_price, i.quantity, TRIM(TO_CHAR(i.unit_price * i.quantity, '999G999D00')) total_price, DECODE(p.product_avail, 'Y', 1, 0) product_avail, bl$dg4o_interface.img(p.product_image,2,2) photo, SIGN(NVL(dbms_lob.getlength(p.product_image), 0)) check_photo FROM demo_order_items i JOIN demo_product_info p ON i.product_id = p.product_id WHERE i.order_id = :ORDER_ID ORDER BY p.product_name


38 - 69

iAdvise

Doxxy

Kolom “Photo” selecteert een BLOB die de afbeelding van het product bevat. Maak gebruik van de specifieke API-call om deze afbeelding op te halen: bl$dg4o_interface.img(, , ,) De functie heeft als parameters:    

De BLOB kolom die de afbeelding bevat De breedte(width) die de afbeelding in het Word document moet krijgen (in cm) De hoogte(height) die de afbeelding in het Word document moet krijgen (in cm) Indicator [0/1] die bepaalt of de afbeelding de originele breedte/hoogte verhouding moet behouden

Zijn zowel de breedte als de hoogte NULL, dan worden de originele afmetingen van de afbeelding genomen. Voorbeeld: SELECT bl$dg4o_interface.img(product_image, 2, 2) AS tag_in_document FROM demo_product_info;

Merk eveneens op dat nog twee kolommen zijn toegevoegd die in de template zullen dienen voor het conditioneel weergeven van gegevens: 1. De kolom PRODUCT_AVAIL geeft de waarde 1 of 0 terug, respectievelijk om aan te duiden of het product nog beschikbaar is of niet. Indien het product beschikbaar is, zal deze in het zwart afgedrukt worden. Is het niet meer beschikbaar, dan verschijnt het betreffende product in het rood. 2. De kolom CHECK_PHOTO is nodig om een “lege foto” te tonen indien er geen BLOB voor het bepaalde product wordt teruggevonden in de databank. Deze kolom geeft eveneens 1 (= foto in databank) of 0 (= geen foto in databank) terug. Wijzig het statement van het “Items”-statement. Vervolgens moeten we nog aanduiden dat we een extra weergave van de gegevens wensen, nl. een table-layout. Hiervoor klikken we bij “Usage in Document” onderaan gewoon op de knop “Add”. Op deze manier kunnen we zoveel weergaves toevoegen als we willen. In dit voorbeeld kiezen we voor “Table”. Als “Recordset Code” vullen we de unieke code “ITEMS_TABLE” in. De tabel zal getoond worden in de “Body of a document”. Bewaar de aanpassingen aan je SQL-statement door op de knop “Save Changes” te klikken. Als je al deze acties op de juiste manier hebt doorgevoerd, zou je het volgende resultaat moeten bekomen: Uitgewerkt voorbeeld Doxxy - Handleiding Versie: 01.02

39 - 69

iAdvise

Doxxy

5.2.2.5 P RODUCT AVAILABLE Indien minstens één product uit de bestelde items niet meer beschikbaar is, wensen we onderaan het rapport nog een extra waarschuwing te tonen. Ook hiervoor hebben we een soort “check”-kolom nodig. Deze selecteren we via het laatste SQL-statement “Product available”. Uiteraard moet deze check enkel gebeuren voor de items uit de bestelling die we net aan het afdrukken zijn. Dit laatste doen we opnieuw door een WHERE-clausule toe te voegen, nl. WHERE order_id = :ORDER_ID. Het SQL-statement met de naam “Product Available” ziet er als volgt uit: SELECT FROM JOIN WHERE AND

SIGN(COUNT(1)) check_product_avail demo_order_items i demo_product_info p ON i.product_id = p.product_id i.order_id = :ORDER_ID p.product_avail <> 'Y'

Als “Parent SQL” vullen we het SQL-statement “Orders” in.


40 - 69

iAdvise

Doxxy

Via “Usage in Document” duiden we de gewenste weergave aan, in dit geval “Paragraph”. Als “Recordset Code” kiezen we “PRODUCT_AVAIL”. De gegevens uit dit statement zullen getoond worden in de “Body of a document”. Tenslotte kijken we na of de gebruikte link variabele ORDER_ID lichtjes blauw geaccentueerd staat. Bewaar je SQL-statement door op de knop “Create” te klikken. Als je al deze acties op de juiste manier hebt doorgevoerd, zou je het volgende resultaat moeten bekomen:

5.2.3 T EMPLATE AANMAKEN (H OE ?) De template bestaat uit twee pagina’s: 1. De eerste pagina bevat de brief aan de klant, met een overzicht van de bestelde artikels in een opsommingslijst. 2. De tweede pagina bevat de bijlage die een overzichtstabel toont van de bestelde artikels met telkens een foto van het betreffende product.


41 - 69

iAdvise

Doxxy

5.2.3.1 D E BRIEF


42 - 69

iAdvise

Doxxy

Vaste afbeelding in de template De brief toont in de linker bovenhoek het logo van de firma. Dit kan heel eenvoudig door het logo in het Word-document te importeren. Microsoft Word-functionaliteiten Kopteksten en voetnoten zijn eveneens functionaliteiten uit Microsoft Word die eenvoudig kunnen worden toegevoegd. Toevoegen van gegevens uit de databank Op plaatsen waar je in de brief gegevens wenst te noteren uit de databank, kan je dit heel eenvoudig doen via de notatie: [BEGIN: MY_RECORDSET_CODE][MY_COLUMN_NAME][END: MY_RECORDSET_CODE] Voorbeeld: [BEGIN: CUSTOMERS][CUST_NAME] … [END: CUSTOMERS] Deze codes moeten exact overeenkomen met de kolom-aliassen uit de SQL-statements. Merk op dat de tag voor het sluiten van de Recordset Code “ORDERS” niet op deze pagina staat. Deze komt op het einde van de bijlage op de volgende pagina. Op die manier kunnen we op de volgende pagina ook nog kolommen uit het ORDER-statement aanroepen. De aandachtige lezer heeft bovendien onthouden dat we bij “ORDERS” als “Usage in Document” gekozen hebben voor “Page Break”. Zo zal er voor elk nieuw order ook telkens een nieuwe pagina begonnen worden. Opsommingslijsten Het weergeven van een opsommingslijst kan via de notatie: 

[BEGIN:ORDERS][CUST_NAME] – [ORDER_DATE] - €[ORDER_TOTAL][END:ORDERS]

De codes voor de recordset en voor de kolommen moeten ook hier exact overeenkomen.


43 - 69

iAdvise

Doxxy

5.2.3.2 D E BIJLAGE


44 - 69

iAdvise

Doxxy

Tabellen Het weergeven van gegevens in een tabel kan via de notatie: Product Description [BEGIN:ITEMS_TABLE][ [PRODUCT_DESCRIPTION] PRODUCT_NAME]

… …

Extended Price in € [TOTAL_PRICE][END:ITEMS _TABLE]

Conditionele weergave Het conditioneel weergeven van gegevens gebeurt via de notatie: [IF:MY_CHECK] … inhoud indien MY_CHECK = 1 … [ELSE:MY_CHECK] … inhoud indien MY_CHECK = 0 … (niet verplicht te noteren, indien leeg) [ENDIF:MY_CHECK] Hierbij is MY_CHECK een kolom uit een SQL-statement die 1 of 0 teruggeeft. Wil je bijvoorbeeld het aantal bestelde producten noteren in het zwart, indien het product nog beschikbaar is, maar daarentegen duidelijk accentueren in het rood, indien deze niet meer in voorraad is, dan wordt dit (let hierbij op het kleurgebruik): [IF:PRODUCT_AVAIL][QUANTITY][ELSE:PRODUCT_AVAIL][QUANTITY][ENDIF:PRODUCT_AVAIL] Wil je onderaan een waarschuwing tonen in het rood, indien één van de producten niet meer beschikbaar is (voor deze check is een apart SQL-statement “Product avail” geschreven), dan wordt dit: [BEGIN:PRODUCT_AVAIL][IF:CHECK_PRODUCT_AVAIL](*) This product is currently not in stock, your order may be delayed. [ELSE:CHECK_PRODUCT_AVAIL][ENDIF:CHECK_PRODUCT_AVAIL] [END:PRODUCT_AVAIL] Afbeeldingen uit de databank Om afbeeldingen uit de databank weer te geven, zijn er twee aandachtspunten: 1. In de query kan je gebruik maken van een specifieke API-call om je afbeelding op te halen: bl$dg4o_interface.img(, , ,) Voorbeeld: SELECT bl$dg4o_interface.img(product_image, 2, 2) AS tag_in_document FROM demo_product_info;

2. In de template volstaat het dan om de volgende tag toe te voegen: [IMG:tag_in_document]


45 - 69

iAdvise

5.2.4

Doxxy

E XTRA FUNCTIONALITEITEN

5.2.4.1 PL/SQL S TATEMENTS Doxxy laat ook toe om specifieke “business logica”, geschreven in PL/SQL te laten uitvoeren bij het begin of het einde van de generatie van een document. Dit is een optionele stap, maar kan bijvoorbeeld gebruikt worden om via het “Oracle Context”-mechanisme een taal-code te zetten of om na het aanmaken van een rapport een spoor weg te schrijven in een log-tabel. Initieel bevat je “PL/SQL”-tab geen enkele lijn.

In dit voorbeeld zullen we een record weg schrijven in een document-logging tabel met de naam van het document en de datum en tijd waarop het document werd aangemaakt. Klik op de knop “Create PL/SQL” in de “PL/SQL”-tab en vul de velden in. Geef een zinvolle naam, een volgnummer en een korte omschrijving. Naast de PL/SQL code zelf is het belangrijk aan te duiden of die logica “Voor” of “Na” het aanmaken van het document moet worden uitgevoerd. Dit doe je via het “Before or After” veld. In het onderstaande voorbeeld zal de code nadien uitgevoerd worden, dus “After”. Merk op dat je ook hier gebruik kan maken van parameters. Dit voorbeeld bevat geen parameters.


46 - 69

iAdvise

Doxxy

5.2.4.2 V ALIDATIE VAN DE TEMPLATE Wanneer je een template oplaadt, voert Doxxy een basis validatie uit op de structuur van de template. Het volgende voorbeeld heeft twee fouten gedetecteerd: 1. De [END: CUSTOMERS] tag ontbreekt 2. De template stelt vast dat er een mogelijke fout is in de naam van de recordset gekoppeld aan het SQL-statement dat de “Items” ophaalt om die te gebruiken in een MS Word List: ITEM_LIST of ITEMS_LIST


47 - 69

iAdvise

Doxxy

5.2.4.3 M ETA D ATA F ICHE Via de Doxxy toepassing is het ook mogelijk een rapport aan te maken met alle belangrijke metadata (SQL statements, PL/SQL statements, parameters en templates) voor jouw document. Indien gewenst kan je deze output bij de technische documentatie van je project voegen. Om het metadata rapport op te vragen, selecteer je eerst het gewenste document in de boomstructuur links. Vervolgens klik je op de knop “Actions”. Een menulijst opent zich. Als je de optie “Print Meta Data” kiest, wordt het gewenste rapport aangemaakt.


48 - 69

iAdvise

Doxxy

Hieronder zie je een fragment van de aangemaakte documentatie.


49 - 69

iAdvise

Doxxy

5.2.4.4 V ISUALISATIE VAN DE TEMPLATE Nog een handige functionaliteit is dat je steeds de templates van een gegeven document kan visualiseren. Je krijgt dan een mooi overzicht te zien van de gebruikte tags in je template. Op die manier kan je gemakkelijk nakijken of je alle tags goed hebt genoteerd in je document. Eventuele fouten worden duidelijk geaccentueerd. Om je template te visualiseren, selecteer je eerst het gewenste document in de boomstructuur links. Vervolgens klik je op de knop “Actions”. Een menulijst opent zich. Klik hierin op de optie “Visualize Template”.

Uit de “Template” lijst kan je de template kiezen die je wenst te visualiseren. Na het drukken op de knop “Visualize” wordt de structuur van de gebruikte recordset codes (met de [BEGIN] en [END] tags), de IFtags en de kolom-tags in een boomstructuur getoond. Deze structuur weerspiegelt de opbouw van je Word template.


50 - 69

iAdvise

Doxxy

Indien de template nog een fout bevat, wordt dit duidelijk gemaakt aan de hand van een “rood kruis” ( ) dat links van het foute element wordt afgebeeld. Uit het volgende voorbeeld kan je concluderen dat:    

de end-tag voor de recordset “customers” ontbreekt de tag “cust_name” verwijst naar een kolom die niet door één van de SQL statements wordt opgehaald. Vermoedelijk is hier een schrijffout in geslopen. er verwarring is over de recordset naam voor de order items: in de template is zowel de tag “item_list” als de tag “items_list” teruggevonden. door het feit dat de tag “item_list” fout is, de Doxxy-engine de kolommen “product_name” en “total_price” niet kan verifiëren tegen een SQL-statement. Daardoor krijgen ook deze tags een invalid notatie.


51 - 69

iAdvise

Doxxy

6 TIPS & TRICKS Op dit moment beschik je over voldoende informatie om zelf aan de slag te gaan met Doxxy. Toch zal je af en toe nog vragen hebben bij hoe je een bepaald probleem moet aanpakken. We kunnen jammer genoeg niet alles behandelen in deze handleiding. We willen je uiteraard wel op de hoogte houden van interessante weetjes en je oplossingen aanbieden voor veel voorkomende vragen.

Onze website http://www.doxxy.eu is hier het ideale hulpmiddel voor. We raden je aan geregeld onze website te bezoeken om op de hoogte te blijven van allerlei tips & tricks en nieuwtjes.

Tips & tricks Doxxy - Handleiding Versie: 01.02

52 - 69

iAdvise

Doxxy

Heb je zelf een probleem en zoek je hier een oplossing voor, aarzel dan niet ons te contacteren via [email protected]. We zullen je vraag zo snel mogelijk proberen te bekijken en je een oplossing aanbieden. Wie weet verschijnen de omschrijving en de bijhorende oplossing van jouw probleem wel op onze website en kunnen ze op die manier een hulp betekenen voor andere Doxxy-gebruikers.

Tips & tricks Doxxy - Handleiding Versie: 01.02

53 - 69

iAdvise

Doxxy

7 DEPLOYMENT Wanneer je een document van een ontwikkelomgeving wilt overzetten naar een test- of productieomgeving, kan je gebruik maken van de export / import functionaliteit die voorzien is binnen de applicatie.

7.1 E XPORTEREN 7.1.1

E XPORT VAN EEN DOCUMENT

Het exporteren van één document wordt gestuurd vanuit een document. Om een document te exporteren, kan je het gewenste document selecteren via de boomstructuur. Als je het “Actions”-menu openklapt, zie je de “Export” optie.

Bij het kiezen van de “Export” optie, wordt automatisch een XML-bestand aangemaakt dat alle metadata en definities van het gekozen document bevat. Zo zal in ons voorbeeld het XML-bestand “de_Order_Confirmation.xml“ aangemaakt worden en vraagt het systeem om dit bestand op een plaats naar keuze te bewaren.

Deployment Doxxy - Handleiding Versie: 01.02

54 - 69

iAdvise

7.1.2

Doxxy

E XPORT VAN MEERDERE DOCUMENTEN

Het is ook mogelijk om meerdere rapporten uit éénzelfde folder tegelijk te exporteren. Deze export wordt gestuurd vanuit een folder. Om dit te realiseren, kan je de gewenste folder selecteren via de boomstructuur. Als je het “Actions”menu openklapt, zie je de “Export Documents” optie.

Vervolgens krijg je een overzicht te zien van alle onderliggende documenten in deze folder. Door de aankruisvakjes bij de gewenste documenten aan te vinken, kan je aanduiden welke documenten je mee wil nemen in je export-bestand.

Klik vervolgens op de knop “Export”. Ook nu wordt automatisch een XML-bestand aangemaakt dat alle metadata en definities van alle gekozen documenten bevat. Zo zal in ons voorbeeld het XML-bestand “Doxxy_multi_export.xml“ aangemaakt worden en vraagt het systeem om dit bestand op een plaats naar keuze te bewaren.


55 - 69

iAdvise

Doxxy

7.2 I MPORTEREN VAN DOCUMENTEN Het importeren van één of meerdere documenten wordt steeds gestuurd vanuit een folder. Om een document te importeren, kan je via de boomstructuur de folder selecteren waaronder het document moet worden aangemaakt. Als je het “Actions”-menu openklapt, zie je de “Import Document(s)” optie.

Bij het kiezen van de “Import Document(s)” optie, wordt een popup-scherm geopend waarin je het geëxporteerde XML-bestand kan ophalen. Als je vervolgens op “Import” klikt, wordt het bestand opgeladen en worden de definities aangemaakt in de Doxxy metadata tabellen. Let wel op! Indien de gekozen folder reeds een document met dezelfde naam bevat, dan wordt deze laatste overschreven.


56 - 69

iAdvise

Doxxy

8 SYSA DMIN / ADMIN MOGELIJKHEDEN Binnen Doxxy hebben we twee “Administrator” profielen: een “Admin” en een “SYSAdmin” rol. De “Administrator” mogelijkheden kan je terugvinden door in de rechterbovenhoek het menu achter de aangemelde gebruiker open te klappen. Enkel indien je als gebruiker voldoende rechten hebt, heb je toegang tot deze “Admin” pagina’s.

Als je als gebruiker de “SYSAdmin”-rol hebt gekregen, verschijnen de volgende menu-opties.

Heb je enkel de “Admin”-rol, dan heb je enkel toegang tot het “Users”-scherm (in lees-modus) en de “Log Messages”.

SYSAdmin / Admin mogelijkheden Doxxy - Handleiding Versie: 01.02

57 - 69

iAdvise

Doxxy

8.1 U SERBEHEER Eén van de items die je terugvindt onder de “Admin”-pagina’s, zijn de “Users”.

Hier kan je gebruikers aanmaken (via de knop “Create”), beheren (door op de gebruikersnaam te klikken) of verwijderen (door op het vuilbak-icoontje te klikken). Een gebruiker heeft steeds een “Username” (om aan te melden) en een volledige naam. Het paswoord kan hier eveneens beheerd worden. Merk ook op dat je aan elke gebruiker “Roles” kan koppelen. Er zijn vier soorten rollen voorzien: 1. “System Administrator”: een gebruiker met deze rol heeft toegang tot alle opties in de Admin folder. Deze rol heb je bijvoorbeeld nodig om gebruikers toe te voegen en hun koppeling aan folders. Ook kan je de logging informatie doornemen en licentie informatie bekijken en aanpassen. 2. “Administrator”: een gebruiker met deze rol heeft een beperkte toegang tot de Admin folder: raadplegen van gebruikers en log boodschappen. 3. “Document Editor”: de gebruiker met deze rol kan folders en documenten aanmaken en beheren. Hij heeft echter geen toegang tot de Admin pagina’s. 4. “Viewer / Reader”: deze gebruiker kan de gegevens in folders en documenten enkel lezen. Hij kan geen nieuwe folders of documenten aanmaken en er ook geen wijzigingen in aanbrengen. Onderaan op de “Users” pagina kan je tenslotte bepalen tot welke folder(s) een gebruiker toegang heeft. In onderstaand voorbeeld merk je dat de gebruiker “DOXXY_USER” de roles “Administrator” en “Document Editor” ontvangen heeft en toegang krijgt tot de folder “DOXXY”. SYSAdmin / Admin mogelijkheden Doxxy - Handleiding Versie: 01.02

58 - 69

iAdvise

Doxxy


59 - 69

iAdvise

Doxxy

8.2 L OGGING Hoewel het Doxxy team zijn uiterste best heeft gedaan om deze Doxxy toepassing zo foutloos en kwaliteitsvol mogelijk op te leveren, kan het altijd voorvallen dat er nog fouten zijn ingeslopen. Wij raden je aan om, in het geval je een mogelijke fout tegenkomt, contact op te nemen met het support team van Doxxy ([email protected]). Afhankelijk van het probleem is het mogelijk dat wij je zullen vragen om bepaalde packages te tracen. Dit is mogelijk via de twee logging pagina’s “Log Configs” en “Log Messages”.

8.2.1 L OG CONFIGURATIONS Op de “Log Configs” pagina kan je het niveau van de logging instellen per package. Deze bepaalt het niveau van de ernst van de boodschappen die moeten doorgelaten en gelogd worden bij het uitvoeren van de package. De log levels variëren van 1 tot 6 waarbij log level 1 het meest strenge niveau is en dus het minst aantal boodschappen doorlaat: enkel de error-boodschappen worden getoond. Log level 6 laat dan weer alle boodschappen door, zoals errors en waarschuwingen, maar ook gewone informatie. Dit is heel nuttig om de code te debuggen.


60 - 69

iAdvise

Doxxy

8.2.2 L OG MESSAGES De resultaten van de tracing worden zichtbaar gemaakt op de “Log Messages” pagina. Je krijgt hier een overzicht van alle boodschappen die je hebt laten genereren. Deze boodschappen kunnen via het “Actions”-menu geëxporteerd worden en doorgestuurd worden naar het Doxxy team die ze zal analyseren. De verkregen boodschappen kunnen voor het Doxxy team nuttige informatie opleveren om de fouten op te sporen en op te lossen.

Het boodschappenoverzicht kan weer leeggemaakt worden via de knop “Purge” in de rechterbovenhoek.


61 - 69

iAdvise

Doxxy

8.3 B EHEREN VAN LICENTIES Via de optie “License” kan je je license key beheren. Standaard zal je hier “TRIAL” zien staan. Dit betekent dat je met een gratis trial versie van Doxxy aan het werken bent. Deze trial versie biedt je dezelfde mogelijkheden als de betalende versie, zonder enige functionele beperking. Je zal enkel op elk gegenereerd document een watermark zien verschijnen. Doxxy-opties (zoals het aanmaken van PDF) zijn niet beschikbaar in de “TRIAL”-versie.

Een licentie van Doxxy aankopen, kan je doen via de website http://www.doxxy.eu of door een mailtje te sturen naar [email protected]. Een licentie is geldig per Oracle database instance. Wij zullen je vragen om ons de database instance naam te bezorgen die we nodig hebben om een unieke key voor jou te maken. Wij zenden je dan de key terug die je op deze pagina dient in te vullen. Meer informatie betreffende de verschillende formules en prijzen, de licentieduur en de support, kan je eveneens terugvinden op onze website.

8.4 B EHEREN VAN S YNONIEMEN Doxxy wordt meestal geïnstalleerd in zijn eigen Oracle schema. Alle SQL-statements worden dus geparsed in het Doxxy-schema. Dit betekent bijgevolg dat dit schema lees-rechten moet krijgen op de tabellen, views of andere objecten uit je applicatie-schema die je wenst te gebruiken in je SQLstatements. In deze laatste kan je dan verwijzen naar deze objecten door deze te laten voorafgaan door de schema-naam van je applicatie. Een alternatieve oplossing is dat je voor elk van deze objecten een PRIVATE SYNONYM aanmaakt in het Doxxy-schema. Dit “Synonyms” scherm laat toe om deze taak uit te voeren vanuit de Doxxy webtoepassing. Het lijst alle objecten uit waarop het Doxxy-schema rechten heeft gekregen (tabellen, views, packages). Indien er al een synoniem bestaat wordt dit mee uitgelijst. SYSAdmin / Admin mogelijkheden Doxxy - Handleiding Versie: 01.02

62 - 69

iAdvise

Doxxy

In het volgende voorbeeld merk je dat voor het applicatie-schema “DEMO” al voor een aantal tabellen synoniemen zijn aangemaakt, en voor andere niet.

Wil je een nieuw synoniem aanmaken, dan klik je op de knop. In het geopende veld kan je de naam van het gewenste synoniem ingeven en vervolgens op klikken om het synoniem te bewaren.

Bestaande synoniemen kan je altijd terug verwijderen via de

knop.


63 - 69

iAdvise

Doxxy

APPENDIX INSTALLATIE I NLEIDING Doxxy 01.02 komt als een export bestand van een Packaged Application voor APEX. Dit bestand bevat dus 1) zowel de APEX UI als 2) alle database objecten als “supporting objects”. Het installatieproces bestaat uit de volgende stappen 1. Maak een specifiek Doxxy database schema aan 2. Maak een workspace in APEX aan en koppel hieronder het Doxxy database schema 3. Meld aan op deze workspace en importeer hierin de toegezonden APEX export file, inclusief de “Supporting Objects”.

Voorbeeld script voor het aanmaken van een specifiek Doxxy schema REM change password + tablespace name to your requirements CREATE USER dg4o_0102 IDENTIFIED BY <my_password> DEFAULT TABLESPACE users TEMPORARY TABLESPACE temp QUOTA UNLIMITED ON users; GRANT GRANT GRANT GRANT GRANT GRANT GRANT GRANT GRANT GRANT GRANT GRANT

CREATE SESSION TO dg4o_0102; CREATE SEQUENCE TO dg4o_0102; CREATE SYNONYM TO dg4o_0102; CREATE PUBLIC SYNONYM TO dg4o_0102; CREATE ANY CONTEXT TO dg4o_0102; CREATE PROCEDURE TO dg4o_0102; DROP PUBLIC SYNONYM TO dg4o_0102; CREATE TYPE TO dg4o_0102; CREATE ANY DIRECTORY TO dg4o_0102; CREATE TRIGGER TO dg4o_0102; CREATE VIEW TO dg4o_0102; CREATE TABLE TO dg4o_0102;

Deze Appendix geeft je de te volgen installatiestappen bij het derde puntje.

APPENDIX Installatie Doxxy - Handleiding Versie: 01.02

64 - 69

iAdvise

Doxxy

I NSTALLATIESTAPPEN BINNEN APEX Deze installatieprocedure gaat ervan uit dat je reeds een APEX-omgeving geïnstalleerd of ter beschikking hebt, met toegang tot een workspace waarin je de Doxxy toepassing mag installeren. We starten in een APEX omgeving en klikken op de “Import” knop om de Doxxy-applicatie toe te voegen.

In de eerste stap selecteer je welk bestand je wil opladen. We duiden hierbij aan dat het gaat om een “Database Application”. Klik op “Next” om naar de volgende stap te gaan.

Het bestand wordt geïmporteerd. Klik op “Next” om de Doxxy toepassing te installeren.


65 - 69

iAdvise

Doxxy

In de volgende stap selecteer je op welk schema alle packages van Doxxy geïnstalleerd mogen worden. Kies het juiste “Parsing Schema” en de gewenste “Build Satus”, in dit geval zijn dit respectievelijk parsing database schema “DOXXY” en build status “Run and Build Application”. Vervolgens selecteer je een optie voor het genereren van de juiste “Application ID” voor de Doxxy toepassing. Klik op “Install Application”.


66 - 69

iAdvise

Doxxy

De applicatie wordt nu geïnstalleerd. Als dit voltooid is, krijg je de vraag of je de “Supporting Objects” wilt installeren. Deze “Supporting Objects” bevatten alle nodige Doxxy objecten en de PL/SQL engine. Beantwoord de vraag bevestigend via het aanklikken van de optie “Yes” en klik vervolgens op “Next”.

Bevestig tenslotte dat de installatie uitgevoerd mag worden. De installatie zal voltooid worden. Dit installatie-proces kan een aantal minuten in beslag nemen. Dus, wees geduldig! Indien je nog de image folder wenst aan te passen, dan kan dat door na de installatie te kiezen voor “Edit application”.


67 - 69

iAdvise

Doxxy

Kies vervolgens voor “Edit Application Properties” zoals in de afbeelding hieronder.

Klik op het vierde tabje “User Interface”. Je ziet nu in de region “General Properties” het label “Image Prefix” staan. Verander dit naar de prefix die voor jouw omgeving van kracht is (bijvoorbeeld: /p/). Vanaf een APEX 4.2 omgeving, kan je dit veld ook leeg laten; APEX neemt dan de default “image folder”.

Klik op “Apply Changes” en run de Doxxy toepassing.


68 - 69

iAdvise

Doxxy

Je kan aanmelden tot de toepassing met de standaard aangemaakte gebruiker sysadmin/sysadmin. Wij raden je aan dit paswoord aan te passen naar de eigen specifieke vereisten.

Als alles goed verlopen is, krijg je de onderstaande pagina te zien.

Je kan altijd controleren of Doxxy goed werkt door het onder de DOXXY > SYSTEM - folder het standaard meegeverde “System Info” rapport uit te voeren. Dit document lijst algemene systeem informatie uit over de geïnstalleerde versie van Doxxy. Vanaf nu kan je zelf aan de slag met Doxxy!


69 - 69

Handleiding. Versie Laatste wijziging: Ontwikkeld door iadvise. Web: Mail:

Recommend Documents