DokumentBroker - Samlet Dokumentation · template_id - UUID for den skabelon, der ønskes genereret et dokument for. fields - indholdet af de felter, der skal gives til skabelonen

DOKUMENTBROKERDokumentation

© Copyright 2012

20. december 2012

INDHOLDSFORTEGNELSE1 Dokumentbrokeren......................1

1.1 Hvad er DokumentBrokeren?............1

1.1.1 Formål.......................................1

1.2 Platform og teknologi........................1

1.3 Komponenter....................................1

1.4 Integrationstyper...............................2

1.5 Kommunikationsprotokol...................2

1.6 Dokument format..............................2

1.7 Forretningslogik................................3

2 Oversigt over API.........................42.1 Konventioner.....................................4

2.2 Kald til DokumentBrokeren...............4

2.2.1 get_client_systems....................4

2.2.2 get_authorization.......................4

2.2.3 generate_document..................5

acknowledge_document...................5

2.3 Kald til skabelonsystemet..................5

2.3.1 get_templates...........................5

2.3.2 get_template_fields...................6

2.4 Retursvar..........................................6

2.4.1 StandardReturType...................6

2.4.2 Return codes.............................6

2.5 REST-API..........................................7

2.5.1 Generelt om kald til API'et:........7

2.5.2 Parametre:................................7

2.5.3 Angivelse af datatype:...............8

2.5.4 Returdata:.................................8

2.5.5 get_authorization.......................9

2.5.6 generate_document..................9

2.5.7 generate_preview....................11

2.5.8 get_client_systems..................12

2.5.9 get_plugin_mappings:.............13

2.5.10 acknowledge_document:......14

2.5.11 get_templates........................14

2.5.12 get_template_fields...............16

2.5.13 get_template.........................16

2.5.14 get_thumbnail_image............17

2.5.15 get_example_image..............18

3 Developers guide.......................193.1 Flow................................................19

3.1.1 Beskrivelse..............................19

3.2 Validering........................................20

3.3 Feltindhold......................................20

4 Sikkerhed....................................214.1 Autentikering...................................21

4.2 Kryptering........................................21

4.2.1 Krypteret kommunikation........21

4.3 Validering........................................26

5 Skabeloner.................................275.1 ODF-skabeloner..............................27

5.1.1 Udvikle skabelonen.................27

5.1.2 Upload skabelonen.................28

5.2 PDF-skabeloner..............................30

5.2.1 Dokumentstrukturer.................30

5.2.2 Bogmærker.............................30

5.2.3 Sprog......................................31

5.2.4 Indholdet.................................34

5.2.5 Datafelter................................34

5.2.6 Billeder....................................34

5.2.7 Forhåndsvisning......................35

5.2.8 Thumbnail- og eksempel-

billeder.............................................35

5.2.9 Eksempler...............................35

5.2.10 Skrifttyper..............................37

6 INSTALLATION GUIDE..............39

7 Release notes............................407.1 Version 0.1.4...................................40

7.2 Version 0.1.3...................................40

7.3 Version 0.1.2...................................41

Dokumentbrokeren

1 DOKUMENTBROKEREN

1.1 Hvad er DokumentBrokeren?DokumentBrokeren er en selvstændig arkitekturkomponent, som uafhængigt af forretnings-

applikation og kontorpakke, genererer dokumenter af forskellige typer og formater, på baggrund

af parametre og skabeloner. DokumentBrokeren kommunikerer med omverdenen ved hjælp af

åbne og hvor muligt standardiserede teknologier.

1.1.1 Formål

DokumentBrokeren har til formål at håndtere skabeloner og gennem serviceinterfaces stille

disse skabeloner til rådighed for eksterne forretningssystemer.

DokumentBrokeren understøtter på kort sigt det åbne og godkendte format ODF, men det er et

mål også at understøtte OOXML og PDF/PDF/A.

1.2 Platform og teknologi

Grundsystemet udvikles på Linuxplatform og ved hjælp af frie og åbne teknologier. Der må ikke

være proprietære elementer som forudsætter indkøb af særlig software.

Kommunikation mellem de enkelte moduler skal foregå ved hjælp af åbne anerkendte

standarder og protokoller. I første omgang implementeres XML-RPC. Men senere er det planen

også at implementere andre, , f.eks. SOAP/REST.

Logning foregår ved hjælp af anerkendte standarder, f.eks. RFC 3164. Se

http://tools.ietf.org/html/rfc3164

Kommunikationen mellem de enkelte elementer/moduler samt mellem DokumentBrokeren og

omverdenen, skal foregå via veldokumenterede grænseflader, hvorved systemet som helhed

bliver skallerbart og modulært. Kommunikationesformen er endnu ikke fastlagt, men kan være

en af SOAP, REST og XML-RPC.

REST og XML-RPC er implementeret.

1.3 Komponenter

DokumentBrokeren er opdelt i en række særskilte komponenter eller moduler. Årsagen er at det

dermed bliver muligt at idriftsætte netop de komponenter som der er behov for. Desuden bliver

systemet skalerbart. Har virksomheden allerede et system til at håndtere logning, skal systemet

logge dertil.

Af samme årsag skal alle komponenter i videst muligt omfang benytte anerkendte standarder,

DokumentBroker - Samlet Dokumentation 1

http://tools.ietf.org/html/rfc3164

Komponenter

for på den måde at gøres fleksibelt og skalerbart.

Følgende komponenter er implementeret:

• Anvendersystem (demo)

• DokumentBroker (motoren)

◦ Administration

• Skabelon container

◦ Brugerinterface til skabeloncontainer

• Log

• Cache

1.4 Integrationstyper

Det største behov findes omkring tekstdokumenter, hvor brevproduktion er højst prioriteret, men

også labels er relevante at kigge på. Der er altså tale om såvel produktion af enkeltobjekter

såvel som brevfletning med et datasæt som input og mange objekter som output.

Integrationstyper:

• Brevfletning - et eller flere breve (rekursivt)

Senere er der planer om også at understøtte:

• Labels

• Brevflet med data (a la fakturalinjer)

• Regneark (datasæt -> regneark)

Håndtering af datasæt er ikke defineret, men CSV-filer skal tages med i betragtning, blandt

andet ved data til regneark.

1.5 Kommunikationsprotokol

På sigt vil DokumentBrokeren kunne benytte flere forskellige protokoller, men i første omgang

XML-RPC og REST.

1.6 Dokument format

Til DokumentBrokeren skal der udvikles en række (mindst tre) dokument plug-ins, som mapper

op mod de enkelte dokumentformater. De forskellige dokumentformater behøver ikke at blive


Dokument format

behandlet med samme teknologi. F.eks. kan ODF-plug-in’et bygges med Python og OOXML

bygges med Java eller .NET..

På nuværende tidspunkt understøtter DokumentBrokeren ODF og PDF.

1.7 ForretningslogikSom udgangspunkt skal der ikke indbygges forretningslogik i DokumentBrokeren.

DokumentBrokeren skal ikke tage stilling til andet end dokumenterne. Enhver forretningslogik

med undtagelse af sikkerhed, skal indbygges i forretningsapplikationerne og ikke i

DokumentBrokeren. På den måde opnår vi det mest fleksible system.

Der vil som nævnt være behov for at tænke datasikkerhed ind i Brokeren, idet der kommer til at

være personfølsomme oplysninger i dokumenterne, som gemmes i f.eks. cache.


Oversigt over API

2 OVERSIGT OVER API

2.1 Konventioner

Alle API-kald navngives med ene små bogstaver. Forskellige ord i API-kaldets navne adskilles

med underscore (_). Alle parametre angives med små bogstaver.

Navnet opbygges således:

• Første ord er udsagnsordet: Hvad udfører denne operation (get, generate, authorize).

• Andet ord er navneordet: Hvilet element er involveret (document, template, user)

• Tredje ord (valgfrit) kan benyttes til at specificere operationen yderligere

(get_template_version, get_template_validation).

2.2 Kald til DokumentBrokeren

2.2.1 get_client_systems

get_client_systems (user_authentication)

Parametre:

user_authentication - et autentikeringstoken som returneret af kaldet til get_authorization.

Returnerer en liste over alle kendte anvendersystemer. Listen er en hashtabel på formen (navn

-> UUID). Givet et navn på et anvendersystem kan denne funktion altså bruges til at finde

systemets UUID.

2.2.2 get_authorization

get_authorization(client_id, password)

Parametre:

client_id - anvendersystemets UUID.

password - anvendersystemets autentikerings-password

Returnerer et autentikerings-token, der skal bruges ved alle API-kald, der kræver autentikering.

Det kan betragtes som et slags "bevis" på, at anvendersystemet lige er logget ind.


Kald til DokumentBrokeren

2.2.3 generate_document

generate_document(user_authentication, template_id, fields)

Parametre:

user_authentication - et autentikeringstoken som returneret af kaldet til

user_authentication.

template_id - UUID for den skabelon, der ønskes genereret et dokument for.

fields - indholdet af de felter, der skal gives til skabelonen. En hashtabel på formen (feltnavn ->

værdi).

Returnerer:

• en URL, der kan bruges til at hente dokumentet fra DokumentBrokeren.

• en returkode

• en SHA-1 checksum

acknowledge_document

acknowledge_document(user_authentication, document)

Parametre:


document - et unikt ID, der betegner et dokument, man allerede har genereret med

generate_document, for eksempel lig URL'en.

Meddeler DokumentBrokeren, at anvendersystemet har hentet det pågældende dokument, som

derfor kan slettes.

Returnerer: Altid 0, med mindre der er problemer med netværksforbindelsen eller lignende.

2.3 Kald til skabelonsystemet

2.3.1 get_templates

get_templates(user_authentication, client_id, context)

2.3.1.1 Parametre


client_id - UUID på det anvendersystem, der ønskes listet.

context - Valgfri parameter for yderligere at filtrere mængden af returnerede templates


Kald til skabelonsystemet

Returnerer en liste af skabeloner for et givet anvendersystem. Returnerer dem som en liste på

formen (navn, UUID, URL).

Et anvendersystem kan bruge dette kald til at beregne UUID'en for en skabelon, hvis det kun

kender dens navn (og omvendt). DokumentBrokeren bruger kaldet til at slå skabelonens URL op

ved generering af dokumentet.

2.3.2 get_template_fields

get_template_fields(user_authentication, template_id)

2.3.2.1 Parametre

client_id


template_id - UUID på skabelonen som der ønskes en liste af felter for.

Returnerer en liste af felter sammen med eventuel valideringsinformation, f.eks. krav om, at

feltet ikke må være tomt. I fase 1 returnerer det en liste af par på formen (name, content_type), hvor content_type altid er string.

2.4 RetursvarAlle DokumentBroker web service kald returnerer et objekt, som består af to dele. Første del er

et element af typen StandardReturType. Det andet objekt vil indeholde den faktiske værdi, som

returneres fra operationen (i tilfælde af succes) eller null (i tilfælde af fejl).

2.4.1 StandardReturTypeDette objekt indeholder læsbare informationer om status for det returnerede resultat. Objektet er

defineret således:

public partial class StandardReturType

{

public string StatusKode;

public string FejlbeskedTekst;

}

Elementet StatusKode vil bestå af en streng med en numerisk kode. Koderne er afledt af

standard HTTP status koder.

Elementet FejlbeskedTekst vil indeholde ekstra detaljer om årsag til fejlen.

2.4.2 Return codesDenne sektion beskriver de forskellige returkoder og tekster Disse vil være indeholdt i delen

StandardReturType for ethvert svar. Tekst som er indlejret i <> vil være erstattet med en værdi


Retursvar

på kørselstidspunktet

200 OK The operation has succeeded without problems.

206 Partial success The operation has succeeded only partially.

400 Bad request Please see rason in the returned <exception_message>

404 Not found

500 Unspecified

501 Not implemented

503 Server not available Template server or DokumentBroker is currently not available.

2.5 REST-APIDocumentBrokeren har et REST-API, som i det følgende gennemgås med de enkelte metoder.

2.5.1 Generelt om kald til API'et:Når der foretages kald til API'et sker det på en af de følgende beskrevne måder.

2.5.2 Parametre:Ved POST og PUT skal data sendes i form af XML eller JSON.

Eksempel på XML-data:

<object>

<authentication>78948...5345</authentication>

<template_id>1234-34...56546</template_id>

<field_data>

<value>Jens Hansen</value>

<value>Pilestræde 34</value>

<field_data>

</object>

Eksempel på JSON-data:

{

”authentication”: ”78948...5345”,

”template_id”: ”1234-34...56546”,

”field_data”: [

”Jens Hansen”,

”Pilestræde 34”

]

}


REST-API

Ved GET og DELETE indsættes data i URL'en. Enten vha. URL-parametre eller som angivet i

metodebeskrivelsen.

2.5.3 Angivelse af datatype:Det er meget vigtigt at angive hvilken datatype der skal anvendes. Dette kan angives i

forespørgslens header, hvor parametrene Accept og Content-type sættes til den ønskede

datatype. Endvidere kan der til URL'en tilføjes parametren f.eks: http://srv/api/metode/?

format=xml.

Man kan anvende én datatype til dataforsendelsen og en anden til modtagelsen. Man skal

erklære hvilken datatype der anvendes til fremsendelse af data, men man kan undlade at

erklære returdatatype. Undlades dette benyttes standarddatatypen, som er JSON.

Man kan også anvende forskellige datatyper til fremsendelse og modtagelse af data. Man kan

således sende data som XML og modtage data som JSON.

2.5.4 Returdata:Returdata kommer tilbage i det format, som er angivet til API'et.

Her er bud på hvad man kan forvente at få tilbage ved et kald.

Eksempel på XML-returdata (get_templates):

<?xml version='1.0' encoding='utf-8'?>

<object>

<templates type="hash">

<item0 type="hash">

<pdf type="boolean">True</pdf>

<thumb type="boolean">True</thumb>

<name>brevskabelon</name>

<file>/media/files/brevskabelon.html</file>

<uuid>be8066e1-f14d-4ce0-a761-123d395b9f8d</uuid>

</item0>

<item1 type="hash">...</item1>

</templates>

</object>

Eksempel på JSON-returdata (get_templates):

{

"templates": {

"item0": {

"file": "/media/files/brevskabelon.html",

"name": "brevskabelon",

"pdf": true,


REST-API

"thumb": true,

"uuid": "be8066e1-f14d-4ce0-a761-123d395b9f8d"

},

"item1": {…}

}

}

2.5.5 get_authorizationDenne metode returnerer en autentikerings-token til videre anvendelse ved efterfølgende API-

kald..

2.5.5.1 HTML-metode: POST

2.5.5.2 Parametre:

<client_id> Kalderens ID.

<password> Kalderens password.

2.5.5.3 Returdata:

<token> En autentikerings-token til anvendelse ved efterfølgende API-

kald.

2.5.5.4 Kald:

URL: ../rest_api/test/get_authorization/

Data:


<object>

<client_id>...</client_id>

<password>...</password>

</object>

{

”client_id”: ”...”,

”password”: ”...”

}

2.5.5.5 Output:


<object><token>...</token></object>

{"token": "..."}

2.5.6 generate_documentDenne metode genererer et dokument ud fra en specifik skabelon.


REST-API


2.5.6.2 Parametre:

<authentication> En streng, som indeholder kalderens autentikerings-token.

<template_id> Et UUID, som refererer til den skabelon, som ønskes anvendt

ved dokumentgenereringen.

<field_data> En liste af værdier, som skal indsættes i skabelonens

datafelter.

2.5.6.3 Returdata:

<hash_key> En hash streng, som kan anvendes til at vurdere hvorvidt et

downloadet dokument svarer til det, som ligger på serveren.

<url> URL'en hvor det genererede dokument kan downloades fra.

2.5.6.4 Kald:

URL: ../rest_api/test/generate_dokument/

Data:


<object>

<authentication>...</authentication>

<template_id>...</template_id>

<field_data type=”list”>

<feltnavnX>...</feltnavnX>

<feltnavnY>...</feltnavnY>

<field_data>

</object>

{

”authentication”: ”...”,

”template_id”: ”...”,

”field_data”: {

”items”: [

”feltnavnX”: ”...”,

”feltnavnY”: ”...”

]

}

}

2.5.6.5 Output:


<object><url>http://127.0.0.1:8000/media/files/

549a967a2c5239f1105d2b2821b68ab5d3f3b3

1e.pdf</url><hash_key>eee88e896836c88ff79

c1ed43c8b1a4243a9ba21</hash_key></objec

t>

{"hash_key":

"6499af4f8cd9ac77ef27dd5c1fbc187565e19

50e", "url":

"http://127.0.0.1:8000/media/files/570

4e4c2ec87200f6bcebd180660437c5c32c12c.

pdf"}


REST-API

2.5.7 generate_previewDenne metode genererer billeder til brug ved forhåndsvisning af et dokument ud fra en specifik

skabelon.


2.5.7.2 Parametre:

<authentication> En streng, som indeholder kalderens autentitet.

<template_id> Et UUID, som refererer til den skabelon, som ønskes anvendt

ved dokumentgenereringen.

<field_data> En liste af værdier, som skal indsættes i skabelonens

datafelter.

<return_format> Angiver i hvilket format billederne skal returneres. Følgende

formater er tilgængelige:

png

tar

tar.gz

tar.bz2

zip

<resolusion> Angiver i hvilken opløsning billederne ønskes. Angives i DPI.

2.5.7.3 Returdata:

<hash_key> En hash streng, som kan anvendes til at vurdere hvorvidt et

downloadet dokument svarer til det, som ligger på serveren.

<url> URL'en hvor det genererede dokument kan downloades fra.

2.5.7.4 Kald:

URL: ../rest_api/test/generate_preview/

Data:


<object>

<authentication>...</authentication>


{

”authentication”: ”...”,


”field_data”: {

”items”: [


REST-API

<field_data type=”list”>

<feltnavnX>...</feltnavnX>

<feltnavnY>...</feltnavnY>

<field_data>

<return_format>...</return_format>

<resolusion>...</resolusion>

</object>

”feltnavnX”: ”...”,

”feltnavnY”: ”...”

]

},

”return_format”: ”...”,

”resolusion”: ”...”

}

2.5.7.5 Output:


<object><url>http://127.0.0.1:8000/med

ia/files/....png</url><hash_key>eee88e

896836c88ff79c1ed43c8b1a4243a9ba21</ha

sh_key></object>

{"hash_key":

"6499af4f8cd9ac77ef27dd5c1fbc187565e19

50e", "url":

"http://127.0.0.1:8000/media/files/...

.png"}

2.5.8 get_client_systemsDenne metode henter en liste over klientsystemer på broker-serveren.

2.5.8.1 HTML-metode: GET

2.5.8.2 Parametre:

<authentication> En streng, som indeholder kalderens uatentitet.

2.5.8.3 Returdata:

<systems> En liste over elementer, som beskriver serverens

klientsystemer.

<itme0..n> Nummererede elementer, som indeholder hvert enkelt

klientsystems data.

<name> Klientsystemets navn.

<uuid> Klientsystemets unikke ID.

2.5.8.4 Kald:

URL: /rest_api/test/get_client_systems/<authentication>/


http://127.0.0.1:8000/media/files/....png

http://127.0.0.1:8000/media/files/....png

REST-API

2.5.8.5 Output:


<object>

<systems type="hash">

<item0 type="hash">

<name>...</name>

<uuid>...</uuid>

</item0>

…

</systems>

</object>

{"systems": {

"item0": {

"name": "...",

"uuid": "…"

},

…

}

2.5.9 get_plugin_mappings:Denne metode henter en liste over tilgængelige plugins på broker-serveren.

Placering: brokerserveren

HTML-metode: GET

2.5.9.1 Parametre:

Ingen.

2.5.9.2 Returdata:

<plugins> En liste over elementer, som beskriver serverens plugins.


plugindata.

<extension> Beskriver filendelsen, som anvender dette plugin.

<plugin> Pluginets navn.

2.5.9.3 Kald:

URL: /rest_api/test/get_plugin_mappings/


REST-API

2.5.9.4 Output:


<object>

<plugins type="hash">

<item0 type="hash">

<extension>HTML</extension>

<plugin>XHTMLPlugin</plugin>

</item0>

...

</plugins>

</object>

{"systems": {

"item0": {

"name": "...",

"uuid": "…"

},

…

}

2.5.10 acknowledge_document:Denne metode bruges til at kvittere for modtagelse af et dokument. Reelt set giver dette kald blot

brokeren lov til at slette dokumentet.

2.5.10.1 HTML-metode: DELETE

2.5.10.2 Parametre:

<authentication> En streng, som indeholder kalderens uatentitet.

2.5.10.3 Returdata:

Ingen.

2.5.10.4 Kald:

URL: /rest_api/test/acknowledge_document/

2.5.10.5 Output:

Intet.

2.5.11 get_templatesDenne metode henter en liste over tilgængelige skabeloner for at specifikt system.

Placering: templateserveren


REST-API

2.5.11.1HTML-metode: GET

2.5.11.2Parametre:

<system_id> ID på det system, for hvilket skabelonlisten skal hentes.

2.5.11.3Returdata:

<templates> En liste over elementer, som beskriver systemets skabeloner.


skabelondata.

<pdf> Et boolsk felt, som fortæller om skabelonen generere PDF

eller ej.

<thumb> Et boolsk felt, som fortæller om der er genereret et thumbnail-

billed for skabelonen.

<file> Angiver placeringen af skabelonen.

<uuid> Skabelonens ID.

2.5.11.4Kald:

URL: /rest_api/test/get_templates/<system_id>/

2.5.11.5Output:


<object>

<templates type="hash">

<item0 type="hash">

<pdf

type="boolean">True</pdf>

<thumb

type="boolean">True</thumb>

<name>...</name>

<file>/media/files/x.html</file>

<uuid>9d8be2ac-...29</uuid>

</item0>

…

</templates>

</object>

{

"templates": {

"item0": {

"file":

"/media/files/x.html",

"name": "...",

"pdf": true,

"thumb": true,

"uuid": "9d8be2ac-...29"

},

...

}

}


REST-API

2.5.12 get_template_fieldsDenne metode henter listen over navne på datafelterne i en specifik skabelon.


2.5.12.2 Parametre:

<template_id> ID på den skabelon, for hvilken feltnavnene skal

hentes.

2.5.12.3 Returdata:

<fields> En liste over navne på datafelterne indeholdt i

skabelonen.

2.5.12.4 Kald:

URL: /rest_api/test/get_template_fields/

2.5.12.5 Output:


<object>

<fields type="list">

<value>...</value>

<value>...</value>

</fields>

</object>

{

"fields": [

"...",

"...",

]

}

2.5.13 get_templateDenne metode henter listen over navne på datafelterne i en specifik skabelon.


2.5.13.2 Parametre:

<system_id> ID for systemet, som kalder metoden.

<template_id> ID på den skabelon, for hvilken feltnavnene skal

hentes.

2.5.13.3 Returdata:

<url> Angiver skabelonens placering.


REST-API

<do_pdf> Et boolsk felt, som angiver om skabelonene genererer

pdf.

2.5.13.4 Kald:

URL: /rest_api/test/get_template_fields/<system_id>/<template_id>/

Data:


<object>

<system_id>...</system_id>


</object>

{

”system_id”: ”...”,


}

2.5.13.5 Output:


<object>

<url>/media/files/x.html</url>

<do_pdf

type="boolean">True</do_pdf>

</object>

{

"url": ”/media/files/x.html”,

”do_pdf”: ”true”

}

2.5.14 get_thumbnail_imageDenne metode henter URL'en til et thumbnail-billed for en specifik skabelon.


2.5.14.2 Parametre:

<template_id> ID på den skabelon, for hvilken billedet skal

hentes.

2.5.14.3 Returdata:

<url> Angiver billedets placering.

2.5.14.4 Kald:

URL: /rest_api/test/get_thumbnail_image/<template_id>/

Data:


REST-API

<object>


</object>

{”template_id”: ”...”}

2.5.14.5 Output:


<object>


</object>

{"url": ”/media/files/x.html”}

2.5.15 get_example_imageDenne metode henter URL'en til et billedeksempel af en specifik skabelon.

Placering: templateserveren

HTML-metode: GET

2.5.15.1 Parametre:

<template_id> ID på den skabelon, for hvilken billedet skal

hentes.

2.5.15.2 Returdata:

<url> Angiver billedet placering.

2.5.15.3 Kald:

URL: /rest_api/test/get_example_image/<template_id>/

Data:

<object>


</object>

{”template_id”: ”...”,}

2.5.15.4 Output:


<object>


</object>

{"url": ”/media/files/x.html”}


Developers guide

3 DEVELOPERS GUIDE

3.1 FlowBeskrivelse af flow for dokument kaldet:

3.1.1 BeskrivelseFør processen kan begynde, skal anvendersystemet logge ind med get_authorization.

1. Anvendersystemet henter en liste over tilgængelige skabeloner. Listen kan evt. gemmes

i en cache, så dette kald ikke skal foretages for hvert eneste brev.

2. Valg af skabelon afhænger af sammenhængen. Måske skal slutbrugeren have mulighed

for at vælge fra en liste, og måske er det givet på forhånd, at i den konkrete kontekst, er

det altid en bestemt skabelon, der skal benyttes.

3. Validering af data mod skabelonens feltregler er frivillig, og det er op til den enkelte

udvikler, at vælge den bedst mulige implementering. Det er vigtigt at de data der sendes

til DokumentBrokeren ”matcher” felter og feltregler i skabelonsystemet. Er dette ikke

tilfældet, returneres en fejlkode.

4. Data til skabelonen kan aflæses fra anvendersystemets data, eller indtastes af

brugeren. Også her afhænger det af sammenhængen, hvordan løsningen skal skrues

sammen, men som udgangspunkt bør alle data, som sendes til skabelonen, også være

gemt i anvendersystemets registre.

5. Data sendes til DokumentBrokeren.


Flow

6. Dokumentet hentes fra DokumentBrokerens cache.

7. Anvendersystemet har mulighed for at kontrollere dokumentets ægthed, ved at

sammenligne det modtagne dokuments SHA1-checksum med den checksum, som

fremgår af retursvaret. De to skal være ens. SHA1-kontrol er frivilligt.

8. Kvittering for dokumentet er vigtig, af hensyn til oprydning i cache. Hvis der ikke

kvitteres, vil dokumentet blive efterladt uslettet. Herfra er det anvendersystemets ansvar,

at dokumentet persisteres.

3.2 ValideringAnvendersystemet kan rekvirere et skema for en skabelons felter og valideringsregler med

metoden get_template_fields.

Hvis et anvendersystem sender data til DokumentBrokeren, som ikke overholder validerings-

reglerne, vil systemet modtage en af følgende returkoder:

206 Partial success DokumentBrokeren er i stand til at danne et dokument, men det

overholder ikke valideringsreglerne

400 Bad request DokumentBrokeren er ikke i stand til at danne et dokument

I første eksempel herover, vil der blive returneret et dokument, men returkode 206 fortæller

anvendersystemet at dokumentet ikke er intakt. Det f.eks. skyldes at et kravsfelt ikke er udfyldt,

eller at der er sendt data til et felt, som ikke genkendes af skabelonsystemet. Husk at fjerne det

defekte dokument med acknowledge_document, også hvis dokumentet ikke skal anvendes.

Det er op til anvendersystemet at tage stilling til, om et dokument, som er returneret med

fejlkode 206, skal anvendes, eller om der skal forsøges dannet et nyt.

3.3 FeltindholdFeltindholdet er som udgangspunkt tekstformat. Formatering af f.eks. tal, beløb og datoer,

foretages af anvendersystemet inden data sendes til DokumentBrokeren

Hvert felt er i stand til at modtage maksimalt 64K (65.536) tegn, men det er ikke hensigts-

mæssigt at overføre så store mængder data. Dataindholdet er rå tekst (UTF-8), dvs. uden

formatteringsmuligheder.


Sikkerhed

4 SIKKERHED

4.1 Autentikering

Anvendersystemerne skal altid autentikere sig før ethvert kald til dokument-brokeren. Det er altid

muligt at logge alle kald med relevante oplysninger om forbindelsen, f.eks. tidspunkt og IP-

adresse. DokumentBrokeren autentikerer kun anvendersystemet på systemniveau, hvilket vil

sige at DokumentBrokeren som udgangspunkt ikke kender slutbrugerens identitet. Såfremt det

ønskes, vil det være muligt at sætte brokeren op, så brugernavnet også overføres og logges,

men det vil ikke indgå i valideringen. Hvert anvendersystem har sine egne login-oplysninger.

4.2 Kryptering

Kommunikationen mellem anvendersystemer og broker bruger SSL/TLS, det vil sige, at

kommunikationen foregår over HTTPS i stedet for HTTP. Det betyder, at passwords samt

følsomme data ikke kan opsnappes af en angriber på samme netværk, for eksempel gennem et

usikkert trådløst netværk. Kræver installering af et SSL-certifikat på dokument-brokeren – to,

hvis skabelonsystemet kører på en server for sig selv.

4.2.1 Krypteret kommunikationDokument-brokeren har til opgave at generere dokumenter med vilkårligt indhold, som let vil

kunne være følsomt af natur. Selvom udvekslingen af dokumenter tænkes at foregå over en

organisations interne netværk, er det alligevel "best practise" at kryptere al kommunikation.

Vi opnår dette ved at tillade en opsætning med SSL, der samtidig autentikerer brugersystemerne

ved hjælp af klientside-certifikater, der lever op til x509-standarden.

Konkret foregår det således:

• Al kommunikation med både dokument-brokeren og skabelonsystemet foregår over

HTTPS.

• Både brokeren og skabelon-serveren udstyres derfor med SSL-certifikater for deres

FQDN.

• Klientside-autentikering kan være optional eller slået helt fra i admin- og

demosystemet.

• Klientside-autentikering er derimod obligatorisk ved anvendelse af brokerens og

skabelonsystemets API, det være sig over REST eller XML-RPC.

• Klientside-autentikeringen er på system-niveau. Når en dokument-broker-integration

installeres i et brugersystem, installeres samtidig et certifikat, der giver adgang til

brokeren.

• Eftersom adgangen er på system-niveau, tænker vi i første omgang, at der kun

udstedes ét certifikat pr. brugersystem, der replikeres til samtlige installationer. Kræves

en mere fintmasket kontrol, vil det være muligt (men i første omgang besværligt) i stedet


Kryptering

at generere ét certifikat pr. installation.

Det er muligt at lave mange variationer i opsætningen og kontrollen af SSL-sikkerhed. I det

følgende beskrives dokument-brokerens standard-opsætning, der først og fremmest sigter på at

være så enkel og effektiv som muligt. Kunder kan tilpasse opsætningen og finmasketheden i

sikkerheden efter deres egne behov. Det vil være en fordel, hvis brugersystemernes klient-

adgang til dokument-brokeren kan foretages gennem en server- eller web-løsning, så det kun er

nødvendigt at opbevare klient-certifikatet ét sted, men det er ikke noget krav, det er helt op til

kundens egne arkitekter (og som sagt vil det altid være muligt at udstede ét certifikat pr.

installation, så installationer kan tilbagekaldes enkeltvis).

Klient-certifikaterne svarer for eksempel til og kan erstattes af OCES Funktions-certifikater

(FOCES). Såfremt dokument-brokeren udbydes af én organisation til en anden over Internettet,

kan den organisatoriske begrænsning, som vi beskriver nedenfor, ændres til at omfatte de

organisationer, som "service-udbyderen" (indehaveren af dokument-brokeren) har samarbejde

med og ønsker at give adgang.

4.2.1.1 Apache-opsætning

I det følgende gennemgås opsætningen af SSL i Apache for dokument-brokerens

vedkommende. Skabelon-systemet skal sættes op helt analogt.

Vær opmærksom på, at hvis skabelon-systemet og brokeren skal køre på forskellige domæner

på den samme server, skal de enten bruge forskellige IP-adresser eller lytte på forskellige porte.

HTTPS kan ikke håndtere virtuelle domæner på samme måde som almindelig HTTP.

Den følgende gennemgang gælder for Apache på Ubuntu- eller Debian-lignende

systemer. Systemet vil også virke f.eks. på Windows eller FreeBSD, men detaljerne

omkring opsætningen er lidt anderledes.

I dokument-brokerens installations-mappe findes en SSL-konfigurationsfil for Apache

(document_broker/etc/document_broker.apache_ssl.conf), der kan kopieres eller

sym-linkes ud i /etc/apache2/sites-available. Som i den sædvanlige installation skal

alle stier tilrettes, så de svarer til den faktiske installation.

Det afgørende nye i denne konfigurationsfil er de direktiver, der aktiverer SSL.

Du skal især være opmærksom på disse linjer:

SSLEngine on

SSLCertificateFile /etc/ssl/private/document-broker.magenta-aps.dk.crt

SSLCertificateKeyFile /etc/ssl/private/document-broker.magenta-aps.dk.key

SSLCACertificateFile /etc/ssl/private/ca.crt

(...)

SSLCARevocationFile /etc/ssl/private/ca.crl


Kryptering

<Location /broker_xml>

SSLVerifyClient require

SSLRequire ( %{SSL_CIPHER} !~ m/^(EXP|NULL)-/ and %{SSL_CLIENT_S_DN_O} eq

"Magenta" )

# So client certificate is REQUIRED, must be issued by our own CA and must not

# be revoked.

</Location>

Vær opmærksom på, at det er muligt at vælge at installere certifikaterne et andet sted, ligesom

opsætningen skal være lidt anderledes, hvis du ikke som her bruger selv-genererede certifikater

på baggrund af en lokal Certificate Authority (CA).

Hvad det egentlig betyder er, at SSL-kryptering altid er slået til, men at klientside-verifikation er

valgfri undtagen i undermappen /broker_xml/, hvor den er obligatorisk. Samtidig accepteres

kun klientsidecertifikater, der er udstedt til en bestemt organisation (her "Magenta"), er udstedt af

vores egen CA og ikke er udløbet.

Ovenstående skal kun ses som et eksempel - det er muligt at indføre meget mere komplekse

valideringer af klient-certifikaterne.

4.2.1.2 Generering og installation af certifikater¶

I installationsmappen er der nu en undermappe, der hedder openssl/.

Den indeholder tre scripts, der kan bruges til at installere en lokal CA på baggrund af et selv-

signeret rodcertifikat. Dette er en fin metode til sikring af trafikken på et lukket intranet, fordi

rodcertifikatet kan installeres direkte på alle de klienter, der skal have adgang til brokeren.

De tre scripts bruger openssl, så hvis ikke du allerede har det på dit system, skal det

installeres først:

sudo apt-get install openssl

Du skal også tilføje følgende i @/etc/ssl/openssl.cnf@:

[ document_broker ]

dir = /etc/ssl/private

database = $dir/index.txt

serial = $dir/serial

private_key = $dir/ca.key

certificate = $dir/ca.crt

default_days = 3650

default_md = md5

new_certs_dir = $dir

policy = policy_match


https://redmine.magenta-aps.dk/projects/dokbrok/wiki/Sikkerhed_og_krypteret_kommunikation#Generering-og-installation-af-certifikater

Kryptering

Længere nede i samme fil skal tilføjes en definition af, hvad der menes med @policy_match@:

[ policy_match ]

countryName = match

stateOrProvinceName = optional

organizationName = match

organizationalUnitName = optional

commonName = supplied

emailAddress = optional

Dette betyder, at for at et certifikat kan verificeres af et andet certifikat, skal countryName (typisk

"DK") og organizationName (f.eks. "Magenta") være det samme. Det er selvfølgelig muligt at

skrue på disse parametre og f.eks. gøre det obligatorisk at angive en kontakt-email i et certifikat.

For at oprette en ny CA og certifikater til de forskellige servere og brugersystemer skal du gå

ned i openssl/-mappen og udføre følgende kommandoer:

4.2.1.2.1 Rodcertifikat

sudo ./new_ca.sh

Dette skal kun køres én gang.

Dette vil give dette output, hvor du promptes for en række ting:

Generating RSA private key, 2048 bit long modulus

.........+++

...............................+++

e is 65537 (0x10001)

You are about to be asked to enter information that will be incorporated

into your certificate request.

What you are about to enter is what is called a Distinguished Name or a DN.

There are quite a few fields but you can leave some blank

For some fields there will be a default value,

If you enter '.', the field will be left blank.

-----

Country Name (2 letter code) [AU]:DK

State or Province Name (full name) [Some-State]:

Locality Name (eg, city) []:

Organization Name (eg, company) [Internet Widgits Pty Ltd]:Magenta

Organizational Unit Name (eg, section) []:

Common Name (e.g. server FQDN or YOUR name) []:Magenta DB CA

Email Address []:[email protected]

Please enter the following 'extra' attributes

to be sent with your certificate request

A challenge password []:

De fleste felter behøver du ikke udfylde - dog skal systemet bruge landekode (DK, som regel),


Kryptering

organisation, common name og email-adresse.

Organisationen skal være den samme for alle de certifikater, vi genererer.

4.2.1.2.2 Brokeren og template-serveren

Servercertifikaterne sættes op med disse kommandoer:

sudo ./new_apache_server.sh document-broker.magenta-aps.dk

sudo ./new_apache_server.sh document-templates.magenta-aps.dk

Du promptes for samme oplysninger som før. Organisationen skal være den samme som i

rodcertifikatet, og "common name" skal være det domænenavn, du har tænkt dig at tilgå

brokeren hhv. skabelonserveren fra. Parameteren til kommandoen (new_apache_server.sh <navn>) kan være vilkårlige gyldige filnavne uden mellemrum - bemærk, at det er den

parameter, der afgør hvad certifikat-filen kommer til at hedde og skal altså afspejles i Apache-

opsætningen. Til sidst bliver du spurgt, om du vil underskrive certifikatet, og det bekræfter du

ved at skrive "y".

Det er vigtigt, at brugersystemerne (dvs. deres browsere og/eller operativsystem og/eller

specialiserede klienter) har adgang til enten CA'ens rodcertifikat eller de to server-certifikater, så

servernes identitet altid valideres, når forbindelsen oprettes. Alternativt kan du indkøbe

servercertifikater fra en officiel CA, hvis certifikater allerede kan formodes at være tilgængelige

på de fleste systemer.

4.2.1.2.3 Brugersystemer

Her bruges kommandoen new_user, f.eks.:

sudo new_user.sh magenta_test

Navnet kan igen være vilkårligt, men bør afspejle det brugersystem, certifikatet udstedes til.

"Common name" skal være brugersystemets UUID, som du bl.a. finder i brokerens admin-

komponent. Bemærk, at disse bruger-certifikater skal overdrages til brugersystemernes

administratorer, som kan sørge at installere dem korrekt på brugernes maskiner. Dette kan

enten ske ved at overdrage administratorerne en PKCS12-fil - eller du kan overdrage den

private og offentlige nøgle i to separate filer. Til sidst bliver du spurgt, om du vil underskrive

certifikatet, og det bekræfter du ved at skrive "y".

4.2.1.3 Placering af certifikaterne

De genererede certifikater bliver anbragt under @/etc/ssl/private/@, en placering, der udmærker

sig ved at kun @root@ på certifikat-serveren har adgang til at læse den. Certifikater til

brugersystemer anbringes under @/etc/ssl/private/users/@. Det er muligt at anbringe dem andre

steder. Det kræver blot, at de tilsvarende stier ændres i scripts samt openssl-konfigurationsfilen.

4.2.1.4 Opsætning af broker og skabelon-server

4.2.1.4.1 Serverne

Når certifikaterne er genereret og SSL er sat op i Apache, skal SSL-autentikering også slås til i


Kryptering

de to serversystemer.

Dette gøres i deres settings-filer (document_broker/document_broker/settings.py og

document_templates/document_templates/settings.py), hvor parameteren

SSL_AUTHENTICATION skal sættes:

SSL_AUTHENTICATION = True

Når dette er gjort, genstartes Apache, og de to server-API'er vil nu se bort fra password-adgang

og kun tage højde for oplysningerne i forbindelsens valide klientside-certifikat. Hvis der ikke er

noget validt klientsidecertifikat udstedt af vores egen CA vil forbindelsen slet ikke blive oprettet,

og samtidig vil de kun give adgang, hvis certifikatets "Common Name" svarer til et klientsystem,

der har adgang til brokeren. Dette checkes ved hvert kald.

4.2.1.4.2 Klienter og demosystemet

Brokerens API er implementeret i XML-RPC og REST, og det ligger uden for dette projekts

rammer at definere, hvordan brugersystemernes programmører skal håndtere integrationen til

brokeren.

Vi har imidlertid implementeret et klient-bibliotek i Python, der leveres sammen med resten af

installationen, og som benyttes af demosystemet såvel som af dokument-brokeren, når den

kommunikerer med skabelonsystemet.

Her er det værd at være opmærksom på, at

• BROKER_BASE_URL og TEMPLATE_BASE_URL skal sættes korrekt i

client/document_broker_settings.py. Ikke mindst skal de angive HTTPS som

protokol.

• Der er indført tre nye parametre SSL_DO_USE, SSL_CERT_FILE og SSL_KEY_FILE,

der skal sættes til True og til stierne til hhv. certifikat- og nøglefilen.

• CLIENT_ID skal stadig sættes, det bruges som en validering.

• Det kan være nødvendigt at konfigurere den software, der kontakter brokeren med XML-

RPC eller REST til at bruge HTTPS og klientside-certifikater. I vores egen klient har vi

f.eks. kodet en lille XML-RPC-proxy i Python. Det afhænger helt af integrationen, og en

nøjagtig specifikation for alle teknologier (Java, .NET, PHP, osv.) ligger uden for dette

projekts rammer.

4.3 Validering

Dokumenter, der returneres fra DokumentBrokeren, kan valideres med en SHA-1-checksum, for

at sikre, at dokumentet er ægte.


Skabeloner

5 SKABELONER

5.1 ODF-skabeloner

5.1.1 Udvikle skabelonen

ODF-skabeloner er skabeloner som kan anvendes af LibreOffice, OpenOffice.org, Apache Open

Office og andre programmer, som understøtter ODF-filformatet. Skabelonerne udvikles ved

hjælp af et af de pågældende programmer, og vi anbefaler at skabelonerne udvikles med

samme program, som skal bruge dem.

Hvis der er særligt behov for at dokumenterne skal kunne arbejde sammen med Microsoft

Office i større omfang, bør skabelonerne udvikles specifikt til dette.

Skabelonerne udvikles på sædvanlig vis, og gemmes som dokumentskabeloner med filendelsen

.ott. Find flere informationer om skabeloner her: http://blog.magenta-aps.dk/kontor/vejledninger/ .

I skabelonerne kan du indsætte "felter", som korresponderer med informationer i fagsystemet.

Det kan f.eks. være modtagers navn og adresse i et brev. I skabelonerne indsætter du felterne

således:

1. Placer markøren der hvor du ønsker at feltet skal placeres.

2. Vælg Indsæt - Felter - Andre....

3. I dialogen Felter, skal du på fanen Variable, indsætte et felt af typen Brugerdefineret

felt. Husk at vælge Tekst som format.


http://blog.magenta-aps.dk/kontor/vejledninger/

ODF-skabeloner

Du kan indsætte flere felter med samme navn. Det kan være relevant, hvis du ønsker at gentage

informationer flere gange i samme brev.

Hvis du ønsker at det pågældende afsnit skal være skjult når feltet er tomt, skal du oprette

endnu et felt i samme afsnit. Af praktiske årsager, er det en god idè at indsætte et mellemrum

efter det brugerdefinerede tekstfelt, og derefter indsætte et skjult afsnit.

1. Vælg Indsæt - Felter - Andre....

2. I dialogen Felter, skal du på fanen Funktioner, indsætte et felt af typen Skjult afsnit.

Udfyld betingelserne som vist herunder:

Bemærk den specielle syntaks i feltet Betingelse, hvor du skal skrive Feltnavn "" . Bemærk to

lighedstegn.

Det er også muligt at "aftale" en syntaks for at skjule afsnit, f.eks. hvis indholdet af feltet er

"skjult". Feltnavn == "skjult"

Bemærk: I LibreOffice er skjulte afsnit som standard ikke skjult. Hvis du vil se resultatet, skal du

vælge i menuen Vis fjerne markeringen ud for Vis skjulte afsnit. Du kan også se resultatet i Vis

udskrift.

5.1.2 Upload skabelonen

I administrationssystemet skal du nu uploade skabelonen. Klik på Tilføj template


ODF-skabeloner

1. I skærmbilledet skal du give skabelonen et sigende navn . Dette navn vil være det

brugerne fremover skal bruge.

2. Vælg ott-filen

3. Vælg Type : OTT-Template

4. Vælg Available for (Her skal du vælge det eller de systemer, som skabelonen skal

bruges i.

5. Vælg Status (Aktiv eller Inaktiv)

6. Version opdateres automatisk

Klik herefter på knappen Gem og fortsæt med at redigere.

Filen uploades nu til serveren, og du kan i bunden af skærmbilledet se en liste over de felter,

som du oprettede i skabelonen. Kontroller, at felterne er korrekte. Bemærk, at hvis du har

gentaget felter, altså indsat flere felter med samme navn, vises de kun èn gang i dette

administrationsskærmbillede.


ODF-skabeloner

Du kan for hvert felt afgøre, om det pågældende felt skal være et kravsfelt, altså om det skal

udfyldes.

Du har mulighed for at tilføje ekstra felter, hvilket giver anvendersystemet mulighed for at sende

ekstra information til DokumentBrokeren. Bemærk dog, at informationer til felter som ikke fysisk

eksisterer i skabelonen, ikke vil blive lagt ind i skabelonen. Informationen er alene af hensyn til

logningen.

5.2 PDF-skabeloner

Templates er XHTML-dokumenter som indeholder felter, som kan holde brugerdefineret data.

5.2.1 DokumentstrukturerNår en template sættes op er der nogle retningslinjer som skal følges for at opnå kontrol over

layoutet i det endelige PDF-dokument og for at dokumentet kan fremstilles. I det følgende vil

disse retningslinjer blive beskrevet.

5.2.1.1 XHTML

Skabelonen beskrives ved hjælp af XHTML, som til forveksling ligner alm. HTML. Der er dog

nogle helt specielle og meget præcise regler for, hvordan skabelonen skal være konstrueret.

Den mest synlige forskel er, at XHTML skal være valid XML, hvilket har stor betydning for

opmærkningen.

5.2.2 BogmærkerDer dannes automatisk bogmærker ud fra h1-6-tags. Bogmærkets tekst vil blive identisk med

overskriftens tekst med mindre andet er defineret. Teksten kan defineres ved at indsætte en title-

attribut. For at bogmærket kan pege på overskriften skal der defineres et id. Det er derfor

nødvendigt at erklære en id-attribut i h1-6-tags. Det er dog valgfrit om man vil tilføje en title-


PDF-skabeloner

attribut.

Andre elementer kan også bogmærkes. Det gøres ved at erklære både en id- og en title-attribut i

elementet.

Figurer (tabeller og billeder) vil komme til at stå nederst i bogmærkelisten og vil have teksten

“Figur: ” foran deres titel.

5.2.3 Sprog

Det er vigtigt at sproget for dokumentet er angivet via lang-attributen i HTML-taget. Dette er en

nødvendighed for dokumentets tilgængelighed.

Formatet for sprogangivelsen er sprogkode (ISO-639) og dialekt (ISO-3166) (da-DK, en-US, en-

UK etc.). Formatet er case sensitive.

5.2.3.1 DIV-tags

Dokumentets struktur er bygget op af div-tags, som adskiller sig fra hinanden med deres id- og

class-attributter.

Forskellen i virkningen af id- og class-attributterne er, at class-attributten definerer indhold, som

er indlejret i dokumentets brødtekst, hvorimod id-attributten definerer statiske elementer, som

forbliver på siderne (sidehoved, sidefod ol.).

For at definere siders opbygning anvendes “variable”, som også defineres via div-tags, hvor

variablens værdi omsluttes af div-taget, som f.eks: <div id=”page_width”>1cm</div>

Eksempel:

Hvis du vil lav et brev, hvor der i højre side er en blok med logo og afsenderadresse, men hvor kun logoet gentages på efterfølgende sider, skal du placere logoet i en blok (id=”sidebar_right”) og afsenderadressen i en anden blok (class=”block_right”).

I tabellerne nedenfor beskrives de id- og class-værdier, som kan anvendes i div-tags til at opsætte dokumentstrukturen.

Attributværdi Funktion

id=”init” Dokumentets initieringsblok. Denne blok

indeholder sidernes struktur. Det er her man

definerer sidehoved, sidefod ol.

Alt indhold skal være indlejret i denne blok.

id=”page_header” Dokumentets sidehoved.


PDF-skabeloner

Vær opmærksom på at margin, padding og

lignende parametre som standard er 0. Disse

kan indstilles i style-attributten.

id=”page_footer” Dokumentets sidefod.

Det samme gælder ved margin etc., som for

page_header.

id=”page_contents” Dokumentets brødtekst.

Det er her sidernes indhold befinder sig.

Det er vigtigt at dette element er en del af init-

blokken.

id=”sidebar_left” En statisk venstrestillet sidebar, som gengives

på samtlige sider.

Det er en meget god idé at definere

elementets bredde, så HTML-visning bliver

som ventet. Det er dog ikke en nødvendighed.

id=”sidebar_right” Det samme som ovenfor, bare højrestillet.

id=”def_p” Definerer overordnet skrifttype og -stil for p-

tags i dokumentet.

id=”def_h1 .. def_h6” Definerer overordnet skrifttype og -stil for h1-

h6-tags i dokumentet.

Attributværdi Funktion

class=”alignment_block” En blok som kan tages i brug, hvis man

ønsker at justere et objekt eller en mængde

tekst til højre eller venstre.

class=”block_left” Anvendes i samspil med alignment_block til

at justere et objekt til venstre. Den skal være

omsluttet af en alignment_block.

class=”block_right” Anvendes i samspil med alignment_block til

at justere et objekt til højre. Den skal

være omsluttet af en alignment_block.

class=”page_break” Anvendes til at fremprovokere et sideskift i


PDF-skabeloner

det endelige dokument.

class=”page_number” Anvendes til at vise den pågældende side.

class=”center_figure_in_parent” Denne blok anvendes til at centrere tabeller

og billeder i en anden blok (eller i

dokumentet generelt).

class=”absolute_position” Anvendes til at placere et element et

vilkårligt sted i dokumentet. Placeringen

angives i style-parameteren vha.

henholdsvis top, left, bottom og right.

class=”table_order_left_to_right_top_down” Denne definition anvendes på tabeller for at

angive læseretningen. Definitionen fortæller

en oplæsningsapplikation, at den skal læse

fra venstre mod højre (kollonnevis) og

oppefra og ned.

class=”table_order_right_to_left_top_down” Denne definition anvendes på tabeller for at



fra højre mod venstre (kollonnevis) og

oppefra og ned.

class=”table_order_top_down_left_to_right” Denne definition anvendes på tabeller for at



oppefra og ned (rækkevis) og fra ventre mod

højre.

Tag Funktion

<div id=”page_width”>..</div> Definerer sidens bredde. Værdien angives i

standard CSS-enheder, som cm, in, px etc.

Man kan også sætte værdien til auto.

<div id=”page_height”>..</div> Definerer sidens højde. Det samme er

gældende, som ovenfor.

<div id=”sidebar_width”>..</div> Definerer bredden af sidebarer. Her skal der

angives en gyldig CSS-værdi (hvis sidebarer


PDF-skabeloner

altså anvendes).

<div id=”header_height”>..</div> Definerer højden af sidehovedet. Her skal der

angives en gyldig CSS-værdi (hvis sidehoved

altså anvendes).

<div id=”footer_height”>..</div> Definerer bredden af sidefoden. Her skal der

angives en gyldig CSS-værdi (hvis sidefod

altså anvendes).

5.2.4 IndholdetDokumentets indhold, herunder brødtekstområdet, men også f.eks. afsenderområdet, bygges op med <p/> som svarer til afsnit.

Overskrifter skal være markeret med <h1/>...<h6/> og altid i logisk rækkefølge. Den første overskrift skal altid være <h1/> og efterfølgende overskrifter skal være enten <h1/> eller <h2/>. Efter en <h2/> må der ikke forekomme andre overskriftsniveauer end <h1/>, <h2/> eller <h3/>. Det er altså ikke tilladt at placere en <h3/> efter en <h1/>. Strukturen skal være komplet og ubrudt.

NB: Tekst må ikke flyde rundt i dokumentstrukturen, derfor skal alle tekstblokke være omlejret af h1-6- eller p-tags. Dette er meget vigtigt for dokumentets tilgængelighed.

5.2.5 DatafelterDatafelter kan defineres af et #-tegn efterfulgt af et feltnavn – f.eks. #modtager eller #afsenders_adresse. Disse felter kan indsættes vilkårlige steder i dokumentet – også i initieringsdelen.

Datafelter indeholdende HTML markeres som #[HTML]feltnavn.

Alle felter skal omsluttes af et span, f.eks.

<span>#modtager</span>

5.2.6 BillederBilleder, f.eks. logo, indsættes i skabelonen ved hjælp af <img src=.../>

1. Billedfilen kan være placeret i skabelonsystemets billedarkiv, hvilket vi anbefaler, men kan også være placeret andre stedet, f.eks. på en hjemmeside: <img src=”http://www.magenta-aps.dk/grafik/toplogo_white.png”/>

2. Billeder skal altid være tilknyttet en forklarende alternativtekst, f.eks. <img src=”http://www.magenta-aps.dk/grafik/toplogo_white.png” alt=”Magentas firmalogo”/>

3. Ved beskrivende billeder (grafer ol.) er det vigtigt at have for øje, at beskrivelsen skal være så fyldestgørende og objektivt at en person, som ikke kan se billedet vil være i


PDF-skabeloner

stand til at få informationen ud af det.4. Følgende billedformater kan bruges:

png, jpg, gif, bmp og svg (såfremt der ikke anvendes skrifttyper, som ikke er implementeret i brokeren)

5. Billedfilen må ikke indeholde transparens (gennemsigtige områder).

5.2.7 ForhåndsvisningDet er muligt at generere forhåndsvisning af dokumenter. Dette kan enten være et billede, flere

billeder pakket (tar, tar.gz eller tar.bz2) eller et HTML-dokument indeholdende billeder.

5.2.8 Thumbnail- og eksempel-billederFor at give brugeren et visuelt indtryk af skabelonerne (gælder indtil videre kun for XHTML-

skabeloner) er det muligt at anvende thumbnail- og eksempel-billeder. Opløsningen af disse

defineres i /[installationsmappe]/document_broker/document_broker/settings.py. Variablene,

som som skal sættes er THUMBNAIL_RESOLUSION og

TEMPLATE_EXAMPLE_RESOLUSION. Disse angives i DPI.

5.2.9 EksemplerI det følgende vil vi give et par eksempler på hvordan div-tags og deres id- og class-attributter kan anvendes til at definere dokumentstrukturer.

5.2.9.1 Eksempel 1: Et XHTML-dokument

<?xml version="1.0" encoding="utf-8" ?><html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="da-DK"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>Simpelt brev med sidehoved og sidefod</title> </head> <body> <div id="init" style="font-family: Liberation Sans; margin: 1cm;"> <div id="page_width">auto</div> <div id="page_height">auto</div> <div id="header_height">1cm</div> <div id="footer_height">1cm</div> <div id="text_mode">start</div> <div id="text_direction">lr-tb</div>⥠ <div id="hyphenize">true</div> <div id="def_p" style="font-family: Liberation Sans Narrow; font-size: 10pt;" /> <div id="def_h1" style="font-family: Liberation Sans; font-size: 14pt; font-weight: bold; padding-bottom: 0.25cm;" /> <div id="page_header" style="margin-top: 0.2cm; margin-left: 1cm; margin-right: 0.2cm;"> <p>#sidehoved</p> </div> <div id="page_footer" style="margin-top: 0.2cm; margin-left: 1cm; margin-right: 0.2cm;"> <p>#sidefod</p> </div> <div id="page_contents"> <h1 id="foerste_afsnit" title="Første afsnit">Et testbrev</h1> <p>Her kommer et afsnit, som vil have samme font, som vi definerede længere oppe.</p> <br/> <p>Nu skifter vi lige til en ny linje og derefter skifter vi til en ny side.</p> <div class="page_break" /> <p style="font-family: Liberation Serif; color: rgb(255,0,0);">Her er en ny side, hvor fonten er ændret vha. style-attributten i p-tagget.</p> </div>


PDF-skabeloner

</div> </body></html>

Ovenstående XHTML-dokument vil generere et PDF/A 1a-dokument med et sidehoved og en sidefod, hvis indhold kan defineres via felterne med samme navn. Først i dokumentets init-del defineres en række variable, som beskriver sidens opbygning. Bredden og højden af siden kan angives eller man kan anvende den automatiske indstilling, som vil fremstille et standard A4-dokument. Når man anvender sidehoved og/eller sidefod skal man definere højden af disse. Denne angivelse skal stemme overens med top- og bundmargin defineret i init-elementet. Man kan vælge om teksten i dokumentet skal falde tilbage til start eller om den skal bredes ud, så den spænder over hele sidens bredde - som i en avisartikel. Dette gøres med text_mode-variablen. Denne kan enten sættes til ‘start’ eller ‘justify’, hvor ‘justify’ betyder at teksten skal spænde over sidens bredde og ‘start’ betyder at teksten skal holdes inde mod startsiden (ligesom teksten i dette dokument). Endeligt slås tekstombrydning til ved at sætte hyphenize-attributten til ‘true’.

Efter specificeringen af dokumentvariable angives fonttyper for h1- og p-tags. Det er disse fonttyper der vil blive anvendt i dokumentet med mindre andet angives senere i dokumentet.

Derefter angives sidehovedet og sidefoden. Det er væsentligt at bemærke, at marginer for disse ikke følger dokumentets marginer. Disse skal sættes for hver blok, ellers går de helt ud til kanterne.

Den sidste blok vi angiver er selve brødtekstarealet, som defineres vha. page_contents.

Læg mærke til at der i brødteksten er anvendt header-tags (h1) og paragraf-tags (p). Dette er en meget væsentlig detalje idet den har stor relevans for det efterfølgende PDF/A 1a-dokument. I PDF/A defineres semantikken af h1-h6- og p-tags. Disse hjælper til med at definere flowet i dokumentet. En anden vigtig ting at bide mærke i er, at der i h1-tagget specificeres en title- og en id-attribut. Disse to attributter definerer tilsammen et bogmærke til overskriften.

Eksemplet viser endvidere hvordan man kan ændre fonttypen inde i teksten ved at definere den i style-attributten i et tag. Desuden anvendes page_break til at fremprovokere et sideskift.

5.2.9.2 Eksempel 2: Justering af tekst

 <div id="init" ...>  <div id="page_contents"> <div class="alignment_block" style="width: 100%; margin-bottom: 1cm;"> <div class="block_left"> <p>#modtagernavn</p> <p>#modtageradresse</p> </div> <div class="block_right"> <p>#afsendelsesby den #afsendelsesdato</p> </div> </div>  </div> </div>


PDF-skabeloner

Ovenfor ses hvordan alignment_block samt block_left og block_right kan anvendes til at henholdsvis højre- og venstrestille to blokke. Disse to blokke vil være på samme højde, men i hver sin side af siden. Endvidere er blokken stylet således at den spænder over hele sidens bredde (jf. width: 100%) samt der indsættes et mellemrum under på 1 cm. højde (jf. margin-bottom: 1cm).

5.2.9.3 Eksempel 3: Indsætning af sidebar

 <div id="init" ...> <div id="sidebar_width">1cm</div>  <div id="sidebar_right"> <div style="background-color: rgb(235,235,235); padding: 0.1cm;"> <div> <h2 title="Kontaktinformationer" id="kontaktinfo">Kontakt</h2> <p><span style="color: rgb(50,50,50);">Telefon: </span><span style="color: rgb(75,75,75);">#afsenders_telefon</span></p> <p><span style="color: rgb(50,50,50);">Adresse: </span><br/><span style="color: rgb(75,75,75);">#afsenders_adresse</span></p> <p style="padding-bottom: 1cm;"><span style="color: rgb(50,50,50);">Website: </span><span style="color: rgb(75,75,75);">#afs_web</span></p> <p><span style="color: rgb(50,50,50);">Sagsnummer: </span><span style="color: rgb(75,75,75);">#sagsnummer</span></p> </div> </div> </div>  </div>

Ovenfor ses hvordan man kan anvende sidebar_right til at definere en statisk sidebar på siden. Læg mærke til at der også er defineret en variabel, sidebar_width, som allokerer bredden af sidebaren. Denne variabel skal defineres, ellers bliver boksen mast ud i kanten af siden. Man må eksperimentere sig lidt frem for at finde den mest optimale bredde.

5.2.10 SkrifttyperSpecielt for PDF/A-dokumenter er, at alle benyttede skrifttyper skal indlejres i dokumentet. Det gælder også de helt basale skrifttyper, som ellers antages at være på alle computere i dag.

Vær opmærksom på, at visse skrifttyper er licenserede, hvilket vil sige, at du muligvis ikke har rettigheder til at distribuere (indlejre) den pågældende skrifttype.

I sit nuværende stadie kan brokeren håndtere følgende åbne skrifttyper:

• Liberation Mono*

• Liberation Sans*

• Liberation Sans Narrow*


PDF-skabeloner

• Liberation Serif*

• Free Serif

(* disse fonte følger med Debian og dets derivater, som Ubuntu, Mint etc. og kan hentes via apt-get)

Det vil naturligvis være muligt at tilføje yderligere skrifttyper efter ønske. Disse skal blot indlejres i brokeren for at kunne anvendes. Endvidere vil vi fremover forsøge at finde andre skrifttyper, som er 100% conformant med PDF/A 1a.

5.2.10.1 Brug af skrifttyperEn overordnet standardskrifttypen skal angives en gang for alle i stylesheet, der ligger i sektionen <div id="init" style=, f.eks. :

<div id="init" style="margin-left: 0.25in; margin-top: 1.0in; margin-right: 0.25in; margin-bottom: 0.75in; font-family:Liberation">

Herefter er det muligt at definere standardskrifttyper og parametre for tags:

<div id="def_p” style="font:12px; font-family:Liberation"/>

<div id="def_h1” style="font:16px bold;font-family:Liberation"/>

Dette gælder for

<p/>, <h1/>...<h6/>Hvis intet er angivet falder indholdet i alle tags tilbage til det i init definerede.

Det er også muligt individuelt at benytte skrifttyper- og egenskaber i den konkrete elementer i f.eks. brødteksten, f.eks.

<p style=”font:14px; font-style:italic;font-family:Liberation” >Kære alle,</p>


INSTALLATION GUIDE

6 INSTALLATION GUIDEInstallationsvejledningen kan findes her:

https://svn.softwareborsen.dk/DokumentBroker/trunk/document_broker/INSTALL

En mere teknisk installationsvejledning findes her:

https://svn.softwareborsen.dk/DokumentBroker/trunk/document_broker/INSTALL.manual


https://svn.softwareborsen.dk/DokumentBroker/trunk/document_broker/INSTALL.manual

https://svn.softwareborsen.dk/DokumentBroker/trunk/document_broker/INSTALL

Release notes

7 RELEASE NOTES

7.1 Version 0.1.4December 19, 2012

• Ticket 6922: TinyMCE Editor added to the demo system.

• Ticket 7144: Change flow in demo, so "Preview" button will create a thumbnail where

the fields are merged.

• Ticket 7151: Fix bug in thumbnail retrieval which caused problems in the demo system.

• Ticket 7152: Fix path error in several HTML templates.

• Ticket 7155: Fix merge error from version 0.1.3 which caused the generate_preview

method to disappear.

• Ticket 7157: Fix bug in thread which caused it not to wait until generation of thumbnails

and XSL-FO template is complete.

• Ticket 7186: Previews are now generated asynchronously and displayed on-page in the

demo application. In order to achieve this, an AJAX method has been developed which

calls generate_preview and displays the image.

• Ticket 7187: Display thumbnail of document instead of example image in field data form

in demo application.

• Ticket 7192: Fix data transfer bug in REST interface.

• Ticket 7214: Bug fixes and improvements in installation script:

• Improved information to user during process.

• Apache port 8000 and ProxyPass for template server added automatically.

• Preinstalled client system allows immediate upload of templates without further

setup.

• Trailing '/' in FQDN parameter is removed.

• Script stops with an error message if the necessary repositories (for installing

dependencies) are not available.

7.2 Version 0.1.3November 30, 2012

• Ticket 6467: Image preview of generated documents (i.e., before actually generating.


Version 0.1.3

• Ticket 6549: Release notes are now included in distribution.

• Ticket 6693: A REST API is now available (as well as XML-RPC).

• Ticket 6694: Secure setup - optionally encrypt communication using wall to wall SSL and

client side certificates for API users.

• Ticket 6697: Perform field merging of XHTML templates in precompiled XSL-FO, not in

XHTML. This change is performance motivated.

• Ticket 6699: Improved design of the demo application.

• Ticket 6991: Support correct page numbering in XHTML templates.

• Ticket 7003: Vastly improved installation process.

7.3 Version 0.1.2September 17, 2012

• Release process improved, using standard setuptools and setup.py

• Ticket 6243: lpod tarball installation was broken, now installs from git repository.

• Ticket 6342: Bookmarks default text fixed.

• Ticket 6351: Code relicensed from MPL to GPL.


adresseStudiestræde 14, 1.1455 København [email protected](+45) 33 36 96 96

Documents

DokumentBroker - Samlet Dokumentation · template_id - UUID for den skabelon, der ønskes genereret et dokument for. fields - indholdet af de felter, der skal gives til skabelonen