14
Implementasjonsguide for integrasjon mot Altinn - English 1 Accenture Altinn Implementation guide for integration against Altinn
Implementasjonsguide for integrasjon mot Altinn -
English
1
Accenture
Altinn
Implementation guide for integration against
Altinn
Implementasjonsguide for integrasjon mot Altinn -
English
2
Change log
Version Date Description of the change Changed by
1.0 31.08.2009 Prepared v1.0 for delivery Accenture
1.1 12.11.2009 Updated after comments by client Accenture
1.2 11.12.2009 Updated after comments by client Accenture
1.3 01.02.2010 Copied to version 2 Accenture
2.0 20.08.2010 Prepared v1.0 for version 2 Accenture
2.0.1 20.01.2011 Prepared v2.0.1 For delivery Accenture
2012.2 04.06.2012 Updates by client ASF
2012.3 14.02.2013 Updates by client ASF
Implementasjonsguide for integrasjon mot Altinn -
English
3
Table of contents Change log ................................................................................................................................ 2 Table of contents ....................................................................................................................... 3 1 Introduction .......................................................................................................................... 4
1.1 Target group for this document .................................................................................... 4 1.2 Main principal for documentation in the implementation guides ................................... 4 1.3 Definitions .................................................................................................................... 4
2 Referred documents and links ............................................................................................. 6 3 High level solution ............................................................................................................... 7
3.1 High level integration sketch ........................................................................................ 7 3.2 Altinn is a platform for services and integration ............................................................ 8 3.3 Security ........................................................................................................................ 8
4 Interface .............................................................................................................................. 8 4.1 Formats ....................................................................................................................... 8
4.1.1 Versioning ............................................................................................................. 9 4.2 Binary attachments ...................................................................................................... 9 4.3 Web services ............................................................................................................... 9
4.3.1 Certificates ...........................................................................................................10 4.3.2 Other web service standards ...............................................................................10 4.3.3 Contracts / formats...............................................................................................10 4.3.4 Coding of messages ............................................................................................10 4.3.5 Web service message examples ..........................................................................10
4.4 File-based integration .................................................................................................13 4.5 Wrapping of data with CDATA mechanism .................................................................13 4.6 Reciepts ......................................................................................................................13
Implementasjonsguide for integrasjon mot Altinn -
English
4
1 Introduction The implementation guides for integration against Altinn can be used by external systems as guidance for how their systems can integrate themselves against Altinn. This document describes the high level architecture for integration against Altinn and security mechanisms that are used for communication between Altinn and external systems. In addition, the following documents exist (see referred documents and links for further reference):
- Implementation guide – Service owners.doc - Implementation guide – End user systems.doc
1.1 Target group for this document
- Those that are going to develop integration against Altinn and need more knowledge about formats and technologies that is used in Altinn integration.
- Architects with a need to know more about how Altinn can fit in to an information architecture
- Those that have a need to know more about Altinn and the possibilities for integration for external systems
1.2 Main principal for documentation in the implementation guides
Content and versioning of the implementation guides should reflect the last version in production. Only the latest version of the services are documented and described. This supports the principle that new service owners and new end user systems should only use the latest version of a service.
1.3 Definitions
Term Description
Archive The component that handles long terms storage of data in Altinn
Workflow The component for handling workflows in Altinn services
Reportee A legal owner of the data that is submitted, for example a company or person
Base64 A standard for representing binary data as text, so that binary data can be a part of for example an XML structure
EAI Enterprise Application Integration – middleware for establishing integration between systems and applications within an organization
ETL Extract, Transform, Load – Common term for products used for extracting and loading of large amounts of data against databases or files
FTP File Transfer Protocol – Protocol for transferring files
HTTP Hypertext Transfer Protocol – Protocol for transfer of data over a network and especially the Internet.
Implementasjonsguide for integrasjon mot Altinn -
English
5
HTTPS Hypertext Transfer Protocol Secure – Encrypted protocol for transfer of sensitive data over a network and especially the Internet.
Reporting service A reporting service is one or several forms defined by a service owner that is filled out in the portal or end user system, possibly being signed, and submitted. Started or submitted reporting services can be kept on the user’s message box in Altinn. The response data is sent to the service owner.
Lookup service The service owners can make information in its own registers (for example enterprise systems or electronic case archive arkiv/case folder) available for the individual users or its representative.
MTOM Message Transmission Optimization Mechanism – A method for efficiently sending binary attachment to and from a web service.
Collaboration service An Altinn service that connects different Altinn services together, that for the end user and/or service owner belong naturally together.
Service owner A government agency, department or enterprise that publishes a Service for use in altinn.
Signing The service owner can define that specific Altinn services (for example reporting service) must be signed one or several times by end user(s) before the particular service can be completed and submitted to Altinn.
Form Form/document defined by a service owner that contains sections that needs to be answered by the one that is using the form. Can be printed on paper or electronically – end user solution utilizes electronic forms.
Form set A collection of forms that belong together. Valid combinations are defined by service owners.
SFTP Secure File Transfer Protocol – Encrypted file transfer connections for safer transfer of sensitive data.
End user system A system that integrates with Altinn on behalf of an Altinn user.
SMTP Simple Mail Transfer Protocol – A standard for sending / transmission of E-mail on the Internet.
SOA Service Oriented Architecture - The concept that applications and automatic processes accesses information resources through standard service interface.
SOAP Simple Object Access Protocol - Independent protocol specification for exchange of structured information through web services
URI Uniform Resource Identifier – A string that identifies a unique resource on the Internet. For example a web page or a web service end point.
Implementasjonsguide for integrasjon mot Altinn -
English
6
Web service Service on the Internet accessed by HTTP/HTTPS that perform a certain task, or a certain type of tasks.
WSDL Web Services Description Language – Technical service contract that describes what operations that exists, and also rules for use (policies)
WS-* A comment term for web service standards that exists.
WS-Security Standard for offering security for communication on a web service.
XML eXtensible Markup Language - XML is a language definition for structuring and description of data.
XAML Standardized format for communicate authorization rules and requests.
XSD XML Schema Definition - Meta description for XML data. Description of how the XML data should be structured and description of all the data elements. Is also used to validate XML data.
2 Referred documents and links
Document Description
Implementation guide – End user systems.doc
This guide describes services in Altinn that are accessible for end user systems.
Implementation guide – Agency systems.doc
This guide describes services in Altinn that are accessible for agency systems.
Link Description
Information to integrator and end user system supplier
(Norwegian) https://www.altinn.no/no/Toppmeny/Om-Altinn/Informasjon-til-fagsystemleverandorer/ (English) https://www.altinn.no/en/Toppmeny/About-Altinn/Information-for-supplierts-of-professional-systems/
Oppgaveregisteret - Overview of form spesifications
http://w2.brreg.no/oppgaveregisteret/spesifikasjon_skjemaliste.jsp
Implementasjonsguide for integrasjon mot Altinn -
English
7
3 High level solution
3.1 High level integration sketch
The service and integration modules in Altinn enable all communication between an end user system and a service owner/agency system. This is valid irrespective of if the need for the data flow is started from the end user or the service owner side. The Altinn platform also utilizes data from public registers as for example the national register() or the Central Coordinating Register for Legal Entities() to complete the data that flows between the actors that are using Altinn. The main integration point for end user systems are the web service that provide an interface to the services that Altinn offers.
Implementasjonsguide for integrasjon mot Altinn -
English
8
3.2 Altinn is a platform for services and integration
Altinn is a portal for communication between government departments and the citizens and companies in Norway. It is also a platform that provides and supports electronic flow of data and integration between these parties. The platform is based on open standard and supports newer and older technologies for integration both by the help of web services and file based integration. The platform will support the following principles with respect to actors and data flow:
Availability – The platform has high availability and is in practice “always open” for data communication. It is preferableto use asynchronous mechanism for delivery of data where this is suitable. This is to permit multiple systems to deliver in parallel in periods with high volumes.
Security – The platform offers mechanism to secure both data content and that users of the solution are identified and have the rights to complete what they are attempting to complete.
o Encryption and decryption of messages and transport. o Signing and check of signing. o Authentication of system and user. o Authorization of system and user.
Interoperability – The platform is based on open standards within integration with focus on the use of XML and Web Services that has wide support in most technologies and solutions. Altinn has an up to date technical platform and is capable of communicating on updated standards (for example within the WS* standards for web services)
Traceability – Receipt and traceability mechanisms exist that support the need for feedback on and tracing of data that are exchanged through the platform.
3.3 Security
All the integrations in Altinn have as a goal to safeguard the security for the systems that are part of the integration. That means securing and encrypting data through transportation, and verifying that those that utilizing the integration to fetch and deliver data has the necessary rights (i.e. are authorized) that are needed to be able to access the data and services. More details can be found in the implementation guides for end user systems and service owners.
4 Interface Altinn offers two different interfaces for most of the functional integrations points.
• Integration by web service - Service definitions (WSDL) describes format for data that is used.
• Integration via XML-files (batch) - Altinn has defined standard format for all XML- integrations.
Implementasjonsguide for integrasjon mot Altinn -
English
9
4.1 Formats
Formats for integration in Altinn are almost exclusively based on use of XML, either through file-based integration or Web Services. The XML-specifications that are used are either defined as standard formats by Altinn to integrate with specific functionality in the solution, XML-specifications that are made public from public metadata sources such as the Norwegian activity register for businesses(oppgaveregisteret) and SERES, or service owners’ own specifications. External systems will use these formats to deliver or fetch data to and from Altinn.
4.1.1 Versioning
The Altinn standard formats that are defined either for file-based integration or Web Services are using versioning of contracts. The versioning is built up around a standard that is widely used by many specification providers. The principle is that the name of a component and the sub component are used for naming and then the year and month when the contract was generated:
http://www.altinn.no/services/<MainComp>[/<SubComp>]/<Year>/<Month> One example of this is:
http://www.altinn.no/services/ServiceEngine/ReporteeElementList/2009/10 The namespaces that are used in Altinn’s service contracts and XML-specifications (XSD) are using this notation for versioning.
4.2 Binary attachments
In Altinn-integration the possibility for transferring binary attachment to/from the solution is used a lot. Since XML and XML in web services are the basis for the standard integration mechanisms that can use XML as transport for this data must be used. Altinn offers two possibilities for this:
Base64 encoding – Here the binary attachment is converted to a text based string that is possible to transport via XML. All file-based integrations to/from Altinn use Base64, but is also one of many options for web services.
4.3 Web services
The Web service interfaces are used principally where there is a need for quick individual data exchanges with Altinn. Altinn offers up to four different internet-addressable end points for each service (URI). These end points support different specifications within web services so that the platform is modern, interoperable and can be used by all external systems that supports web services.
Basic Http (SOAP 1.1) (Service contracts named with ExternalBasic) - Basic use of web services without much support for newer and modern WS-*
standards. This is still considered the standard most technical platforms have the ability to integrate with, but lacks some mechanisms that support web services including safety.
- Binary attachments using Base64 encoding
Implementasjonsguide for integrasjon mot Altinn -
English
10
WS Http (SOAP 1.2) (Service contracts named with External) - Støtter mer avanserte mekanismer og nyere standarder innen web services.
Altinn tilbyr dette for å støtte de plattformene som benytter WS-Security. - Støtte for nye web service standarder WS-* og gjør det mulig for Altinn å følge
denne utviklingen i takt med systemer som ønsker å bruke Altinn web services. - Binære vedlegg benytter Base64 enkoding - Provides supports for more advanced security and compression mechanisms for
web services. Altinn offers this to support the platforms that use WS-Security and MTOM.
- Support for new web service standards WS-* and allows Altinn to follow this development in line with systems that wish to use Altinn web services.
- Binary attachments using Base64 encoding
4.3.1 Certificates
Altinn uses web services not specific certificates for signing or encrypting the data before the report is sent from the client side. Encryption Security for web services is based on the use of HTTPS. Enterprise Certificates can be used for authenticating enterprise users. Enterprise users will use username, password and enterprise certificate for authentication. For “BrokerService”, the use of certificates for signing and / or encryption can be used. This must then be set up specifically for a service and be agreed upon between the parties involved in the mediation service.
4.3.2 Other web service standards
Altinn currently offers SOAP in different formats as standards for web services. Other standards for services, such as REST or XML / HTTP are not used.
4.3.3 Contracts / formats
The structure of data that can be sent to Altinn is based on specifications managed by external metadata sources such as the the Norwegian activity register for businesses (Oppgaveregisteret) or SERES.
4.3.4 Coding of messages
Altinn uses UTF-8 for submission and retrieval of data through web services.
4.3.5 Web service message examples
Here are some examples of how a SOAP message that can be used against Altinn looks for the different standards that Altinn supports. The examples show one variant, and in terms of content and parameters, see the chapter that describes the interface for each web service and the operations on these.
Implementasjonsguide for integrasjon mot Altinn -
English
11
4.3.5.1 Basic
4.3.5.1.1 Basic with Base64 attachment
Attached example shows the whole http message that is sent in this case (12 Kb)
SOAP_Basic_Base64Attachment.xml
POST
https://www.altinn.no/IntermediaryExternal/IntermediaryInboundBa
sic.svc HTTP/1.1
Content-Type: text/xml;charset=UTF-8
SOAPAction:
"http://www.altinn.no/services/Intermediary/Shipment/Intermediar
yInbound/2009/10/IIntermediaryInboundExternalBasic/SubmitFormTas
kBasic"
User-Agent: Jakarta Commons-HttpClient/3.1
Host: www.altinn.no
Content-Length: 11248
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns="http://www.altinn.no/services/Intermediary/Shipment/In
termediaryInbound/2009/10">
<soapenv:Header/>
<soapenv:Body>
<ns:SubmitFormTaskBasic>
<ns:systemUserName>1</ns:systemUserName>
<ns:systemPassword>altinn1234</ns:systemPassword>
<ns:userSSN>19105411084</ns:userSSN>
<ns:userPassword>1234567</ns:userPassword>
<ns:userPinCode>12345</ns:userPinCode>
<ns:authMethod>TaxPin</ns:authMethod>
<ns:formTaskShipment>
…
…
…
Implementasjonsguide for integrasjon mot Altinn -
English
12
4.3.5.2 WS
4.3.5.2.1 WS with Base64 attachment
Attached example shows the whole message that is sent in this case.
POST
https://www.altinn.no/IntermediaryExternal/IntermediaryInbound.s
vc HTTP/1.1
Content-Type: application/soap+xml;charset=UTF-
8;action="http://www.altinn.no/services/Intermediary/Shipment/In
termediaryInbound/2009/10/IIntermediaryInboundExternal/SubmitFor
mTask"
User-Agent: Jakarta Commons-HttpClient/3.1
Host: www.altinn.no
Content-Length: 3254
<soap:Envelope
xmlns:ns="http://www.altinn.no/services/Intermediary/Shipment/In
termediaryInbound/2009/10"
xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
<soap:Header xmlns:wsa="http://www.w3.org/2005/08/addressing">
<wsse:Security soap:mustUnderstand="true"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-
wss-wssecurity-secext-1.0.xsd">
<wsse:UsernameToken wsu:Id="UsernameToken-20285642"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-
wss-wssecurity-utility-1.0.xsd">
<wsse:Username>412</wsse:Username>
<wsse:Password Type="http://docs.oasis-
open.org/wss/2004/01/oasis-200401-wss-username-token-profile-
1.0#PasswordText">altinn1234</wsse:Password>
<wsse:Nonce>3UyySczvqkXxOXGaSPeRCA==</wsse:Nonce>
<wsu:Created>2009-08-31T22:56:46.212Z</wsu:Created>
</wsse:UsernameToken>
</wsse:Security>
<wsa:Action>http://www.altinn.no/services/Intermediary/Shipment/
IntermediaryInbound/2009/10/IIntermediaryInboundExternal/SubmitF
ormTask</wsa:Action>
<wsa:To>https://www.altinn.no/IntermediaryExternal/IntermediaryI
nbound.svc</wsa:To>
</soap:Header>
<soap:Body>
<ns:SubmitFormTask>
<ns:userSSN>19105411084</ns:userSSN>
<ns:userPassword>1234567</ns:userPassword>
<ns:userPinCode>12345</ns:userPinCode>
<ns:authMethod>TaxPin</ns:authMethod>
<ns:formTaskShipment>
Implementasjonsguide for integrasjon mot Altinn -
English
13
SOAP_WS_Base64Attachment.xml
4.4 File-based integration
Interfaces with file-based integration are mainly used for larger data amounts, and/or where there is no need for immediate response on the data exchange. There is no absolute limit in Altinn on how large «larger data amounts» are, or how large data amounts that can be sent via Web Service, but the following rule of thumb can be used:
Web Service > 30 MB/100 elements > batch
For file-based integration with Altinn the FTP protocol is used, preferably SFTP (FTP over SSH). Two methods are available:
Altinn can fetch data from the external party’s system
The external party can deliver data on a defined Altinn area, i.e. a SFTP server must be established by the external party.
Details and adjustments of the file-based transfer are clarified when establishing a new connection.
4.5 Wrapping of data with CDATA mechanism
Several of Altinn’s services are based on that structured XML shall be transferred in a envelope message that contains metadata about that which is being transferred. One example on this is reporting service that delivers one or multiple forms that each are according to an XML specification delivered by on one or multiple metadata suppliers as for example the Norwegian activity register for businesses (oppgaveregisteret). To be able to do this the structured XML-part is packed into a CDATA-element so that the service does not regard this as a package with data and not as a service parameter in regards to the contract for the operation. CDATA is a mechanism for transferring data where the content should not be validated together with the data that closes it, but is handled as a string with data. The contents inside the CDATA element does not need to be further encoded. A CDATA-element is defined as a ordinary XML element the following way: <Data> <![CDATA[within the curly bracket a string with data is stated]]></Data>
4.6 Reciepts
Altinn uses a receipt mechanism so that external systems should have insight into the reporting process in regards to reception, control and processing of data that is sent in. This receipt contains logistics around shipment and processing of data.
Implementasjonsguide for integrasjon mot Altinn -
English
14
It will also be possible for an integration actor to give a receipt on the receipts that is held in Altinn so that another sender can see that for example a service owner has received and validated data on their side. Receipts are used and updated for integrations where: • Altinn receives messages / data for processing. • When me messages / data is validated and passed on for processing. More specific information about how receipts are used in the individual integrations can be found in the underlying implementations guides.
