Reference implementations 11th November 2010 Malmö Thomas Ravnholt PEPPOL Reference Implementation team

Reference implementations

Reference Implementation team Team of 5 experienced developers – some from NemHandel (Danish eProcurement) Developed 20+ solutions/libraries Approximately 6 months of development time – A lot of changes in the specifications – Complete rewrite from 0.8 to 0.9 Created a test infrastructure with live Access Points etc.

Reference Implementations START AP: The Secure Trusted Asynchronous Reliable Transport (Java,.NET) – The main protocol for sending messages LIME AP: The Lightweight Message Exchange Transport (Java,.NET) – A lighter protocol towards senders SMP: Service Metadata Publisher (Java) SML: Service Metadata Locator (Java) DNS: A PEPPOL domain has been set up

Technology (Java) Java – JDK 6 – Java Metro – Ant 1.7.x+ – Apache Tomat 6.0.x – Tested on – Windows Vista – Ubuntu 8.10

Technology (.NET C#) Microsoft.NET Framework 3.5 Windows Identity Foundation Internet Information Services (IIS) Custom build from MS – System.IdentityModel.dll and System.ServiceModel.dll Tested on – Windows XP, Windows Vista, Windows 7

PEPPOL repository PEPPOL implementations is stored in Subversion at – svn.forge.osor.eu Everyone can check out the source code Need certificate to commit source code Each project contains a trunk and several tags

Java START projects busdox-transport-start-library – Core classes for building a START client busdox-transport-start-client – A sample START client busdox-transport-start-server – Implementation of a START Access Point busdox-transport-commons – Generic busdox classes shared by LIME and START Library/START/tags/

.NET START projects STARTLibrary – Core types for building START Access Points and Clients + WSDL and scheams STARTAccessPoint – Implementation of the START Access Points SampleSTARTClient – A sample START client ransportlibrary/tags/

.NET LIME projects LIMELibrary – Core types for building LIME Access Points and Clients + WSDL and Schemas LIMEService – Implementation of the LIME Access Points IOLayerLibrary – Message store ransportLibrary/tags

Java LIME projects busdox-transport-lime-library – Core classes for building a LIME client busdox-transport-lime-client – A sample LIME client busdox-transport-lime-server – Implementation of a LIME Access Point busdox-transport-commons – Generic busdox classes shared by LIME and START Library/LIME/tags/

Service Metadata Locator (Java) Management service – A webservice for manipulating SML records Management client library – Core classes for building a Management Client Management console client – A sample Management client viceMetadataLocator

Service Metadata Publisher (Java) RESTBinding – Service Metadata Publisher REST service RESTBindingLibrary – A Service Metadata Publisher client library CommonLibrary – Generic classes and schemas viceMetadataPublishing

Deployed.NET Access Points START.NET – 1.amazonaws.com:8444/PeppolAccessPoint1/STARTAccessPoint.svc – 1.amazonaws.com:8444/PeppolAccessPoint/STARTAccessPoint.svc LIME.NET – 1.amazonaws.com:8081/limeService1.0Even/ResourceService.svc – 1.amazonaws.com:8081/limeService1.0UnEven/ResourceService.svc

Deployed Java Access Points START JAVA – transport-start-server-1.0.1/accesspointService – transport-start-server /accesspointService LIME JAVA – transport-lime-server-1.0.1/wstransferService – transport-lime-server /wstransferService

Deployed DNS, SML and SMP A PEPPOL DNS has been configured – Used by reference implementations and demonstrator clients SML Mangement interfaces – 1.amazonaws.com/ServiceMetadataLocatorManagement/ managebusinessidentifier – 1.amazonaws.com/ServiceMetadataLocatorManagement/ manageservicemetadata SMP REST interface – 1.amazonaws.com:8080/

Test data Test data have been created for id’s in the range – 1-16 (0010: ) – (0010: ) – (0010: ) A lot of document types and process types for each identifier Endpoints point to reference implementation AP’s (but can be changed) Obtain Identifier for development and testing from

PEPPOL release Changes to come – Update of namespaces when moving under OASIS – Upgrade to new PEPPOL certificate infrastructure – Optimizing RM endpoint handling RM endpoint bug accepted by Metro (priority 2) – Support for tokentype on SecurityTokenReference – Better protocol test tools (only ping now) – Generel improvements (performance, caching etc.)

Purpose of Reference Implementation Use the Reference Implementations – as a fast way to get started building you own AP’s Source code available Complete test infrastructure deployed Testdata ready – as inspiration – a quick way to test compliance of AP clients

Using the SMP and SML

Sending documents SMP Registry Company X START AP Country A START AP Country B Company Y Obtain metadata

Steps for sending documents 1)Obtain metadata for the recipient ID 2)Get endpoint from metadata for specific document and process type 3)Create SOAP message metadata headers and SAML token 4)Send message to AP

What is a START message A message from one AP to another SOAP headers – Sender and Recipient (participant id) – Document type (order, invoice,…) – Process type (ordering, billing, payment, …) – Message ID SOAP body – The CEN BII UBL XML payload

Participant identifiers Senders and receivers of message are addressed by participant identifiers In URI’s – {identifier scheme}::{type id:id} – busdox-actorid-upis::0010: Participant identifiers logically consist of a scheme identifier and the business identifier itself and a type – Type is 4-digit number indicating the type of participant id such as GLN, DUNS, CVR – Scheme indicates the textual format of the participant id

Service Metadata Publisher (SMP) Holds info on message receivers Several SMP’s in the PEPPOL infrastructure Each SMP hold metadata for a unique subset of identifiers SMP’s are located using a DNS scheme with participant identifiers – avoids having a central server for locating SMP’s

Service Metadata Publishers (SMP) Metadata contains – Document and process types accepted by a receiver – Address of receivers Access Point Metadata can be read using plain HTTP (REST interface) Metadata can be updated using a management API (webservice)

SMP metadata XML 0010: urn:oasis:names:specification:ubl:schema:xsd:AcceptCatalogue-2::AcceptCatalogue##UBL- 2.0 BII amazonaws.com:8444/PeppolAccessPoint/STARTAccessPoint.svc ….. test …

Tools: SMP Registration Site Developer tool (RegistrationSite) – View, update and delete SMP Metadata Reference implementation of SMP contains a RegistrationSite – 1.amazonaws.com/RegistrationSite/

Locating the SMP

Locating the SMP using DNS All recipients have a CNAME in the DNS Host names are constructed using info on the recipient SMP host = ”B-”+MD5(id)+scheme+base domain actorid-upis.sml1.smloc.org/.... – 0010: MD5’ed is e49b223851f6e97cbfce4f72c3402aac

Is the recipient ID in the DNS?

Getting metadata on runtime SMP REST interface – scheme}::{id}/services/{docType} recipient scheme= "busdox-actorid-upis”; recipient= "0010: "; documentIdScheme = "busdox-docid- qns::urn:oasis:names:specification:ubl:schema:xsd:AcceptCatalogue-2"; documentIdValue = "AcceptCatalogue##UBL-2.0"; processIdScheme = "cenbii-procid-ubl"; processIdValue = "BII01"; upis.sml1.smloc.org/busdox-actorid- upis%3A%3A0010%3A /services/busdox-docid- qns%3A%3Aurn%3Aoasis%3Anames%3Aspecification%3Aubl%3Aschema %3Axsd%3AAcceptCatalogue-2%3A%3AAcceptCatalogue%23%23UBL-2.0

SMP metadata XML 0010: urn:oasis:names:specification:ubl:schema:xsd:AcceptCatalogue-2::AcceptCatalogue##UBL- 2.0 BII amazonaws.com:8444/PeppolAccessPoint/STARTAccessPoint.svc ….. test …

Obtaining the AP url from SMP (C#) public static string BuildAccesspointUrl(string SMLDomain, string RecipientIdentifierValue, string RecipientIdentifierScheme, string DocumentIdentifierValue, string DocumentIdentifierScheme) { var url = " + string.Format("b-{0}.{1}.{2}/{1}::{3}/services/{4}", Utilities.GetMD5Hash(RecipientIdentifierValue), RecipientIdentifierScheme, SMLDomain, RecipientIdentifierValue, DocumentIdentifierScheme + "::" + DocumentIdentifierValue ).Replace(":", "%3A").Replace("#", "%23"); return url; }

Service Metadata Locator (SML) Think of the SML as the interface to the PEPPOL DNS Management interface for DNS CNAME records – Create, update, delete SMP’s uses the SML interface for – Registering a new company/business

Metadata life cycle

Developer tool: listdns 1.amazonaws.com:8080/ServiceMetadataLocatorManagemen t/listdns

Typical SMP/DNS errors Host not found – Check ID with nslookup or listdns tool – Is the ID scheme right?, the MD5? actorid-upis.sml1.smloc.org/.... The SMP responds with a HTTP 404 error – Check the document type and scheme No access point URL – Check the process type and scheme

Building Access Points

Infrastructure

Sending documents SMP Registry AP client START AP 1 START AP 2 Obtain metadata

START message flow

START Access Points START AP’s can send and recieve documents Enables reliable and secure transport of documents between START AP’s START transport layer does not inspect the doc in soap payload (only SOAP headers are used and verified) START AP is resembles a router START AP’s may offer the LIME interface towards senders

WS-Addressing Transport neutral addressing of web services No final spec release yet. Both LIME and START uses WS-Adr SOAP Headers: xs:anyURI xs:anyURI xs:anyURI endpoint-reference

WS-Transfer Protocol for accessing and uploading resources Core Protocol – CREATE (allocate Id and endpoint for a ressource) – PUT (upload the ressource) – GET (a ressource) – DELETE PEPPOL LIME: CREATE, PUT, GET, DELETE PEPPOL START: CREATE, PUT

WS-Reliable Messaging Helps ensuring messages are delivered Core Protocol – CreateSequence + response – Messages in the sequence – Acknowledgement – Resend of unacknowledged message – TerminateSequence + reponse Only START uses RM

WS-Security and SAML A few security specs are involved – WS-Security – WS-SecurityPolicy – SAML 2.0 START uses SSL, SAML, Signatures, X509 LIME uses SSL, Basic Authentication

Specifications CommonDefinitions.doc PEPPOL_Identifiers.doc STARTProfile.doc LIMEProfile.doc ServiceMetadataLocator.doc ServiceMetadataPublishing.doc ecifications/

WSDL and schemas Identifiers-1.0.xsd – Core identifiers like ParticipanIdentifier and DocumentType LIME-Types-1.0.xsd – PageList START-Types-1.0.xsd – Ping type ServiceMetadataLocatorTypes-1.0.xsd – CreateParticipantIdentifier, PublisherEndpoint and more ServiceMetadataPublishingTypes-1.0.xsd – Endpoint, ServiceInformation, Process and more ws-tra.wsdl – Draft version of WS-transfer with PEPPOL security policy ema/1.0/ DL/

Identifiers-1.0.xsd - Common identifiers for WSDLs and Schemas - …

ws-tra.wsdl Simple wsdl with 4 methods (CREATE,PUT,GET, DELETE) Snippet: …… …..

ws-tra.wsdl with policy in START …. …. …

START SAML Token <saml:Assertion ID="a123“ IssueInstant=" T12:00:00“ Version="2.0" …. 0010: urn:oasis:names:tc:SAML:2.0:ac:classes:X509 <saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" Name="urn:eu:busdox:attribute:assurance-level"> 3

LIME Access Points Does the same as START AP’s – Looks up the destination AP (by receiver ID) – Sends the message to destination AP – Sends a receipt to the sender Added functionality – Stores incomming messages – Allows message polling – like an POP3 box SSL and Basic Authentication – No SAML, no RM – Easy to implement clients

LIME schemas and WSDL’s Bussiness ID, document and process type – Identifiers-1.0.xsd Paging in LIME – LIME-Types-1.0.xsd WS-Transfer (CREATE,PUT,GET,DELETE) – ws-tra.wsdl WS-Transfer types – ws-tra.xsd

LIME message flow

LIME code sample (GET-LIST) private void getMessageList(EndpointReferenceInterface endpointReference) throws Exception { Factory factory = new Factory(); Inbox inbox = factory.createInbox(); List messageReferences = inbox.getMessageList(createCredentials(), endpointReference); if (messageReferences != null && messageReferences.size() > 0) { for (MessageReferenceInterface messageReference : messageReferences) { System.out.println("INBOX - MESSAGE: " + messageReference.getMessageID()); } } else { System.out.println("INBOX - NO MESSAGES"); }

LIME code sample (GET) private void getMessage(String messageID, EndpointReferenceInterface endpointReference) throws Exception { Factory factory = new Factory(); MessageReferenceInterface messageReference = factory.createMessageReference(); messageReference.setMessageId(messageID); messageReference.setEndpointReference(endpointReference); MessageInterface fetchedMessage = factory.createInbox().getMessage(createCredentials(), messageReference); if (fetchedMessage != null) { System.out.println("INBOX - MESSAGE: " + messageID); System.out.println(fetchedMessage); streamMessage(fetchedMessage, System.out); } else { System.out.println("INBOX - MESSAGE NOT FOUND: " + messageID); }

LIME code sample (CREATE/PUT) private MessageInterface createSampleMessage(Factory factory, String xmlFilename, String senderID, String receiverID) throws Exception { String businessIdScheme = "busdox-actorid-upis"; String documentIdScheme = "busdox-docid- qns::urn:oasis:names:specification:ubl:schema:xsd:AcceptCatalogue-2"; String documentIdValue = "AcceptCatalogue##UBL-2.0"; String processIdScheme = "cenbii-procid-ubl"; String processIdValue = "BII01"; MessageInterface message = factory.createMessage(); if (xmlFilename != null) { message.setDocument(loadXMLFromFile(xmlFilename)); } message.setDocument(loadXMLFromFile(xmlFilename)); …. message.getSender().setBusinessIdentifier(senderID); message.getSender().setScheme(businessIdScheme); ….. return message; }

LIME code sample (CREATE/PUT) private String testSendMessage(MessageInterface message, EndpointReferenceInterface endpointReference) throws Exception { Outbox outbox = Factory().createOutbox(); String messageid = new outbox.sendMessage(createCredentials(), message, endpointReference); System.out.println("OUTBOX - MESSAGE DELIVERED: " + messageid); return messageid; }