Implementation guide

​Summary

Nets supplies distribution solutions – both electronic- and hard copy solutions – to Nordic businesses and public sectors. Nets Share is a standard distribution concept for electronic and hard-copy distribution which contributes to interaction, cost reduction, the environment and building added value for all its users. Nets Share simplifies distribution for the sender. Nets Share is a distribution solution which enables businesses to distribute information to recipients through electronic or physical media/channels. The sender is free to manage distribution by selecting the distribution channels to be offered to the recipient. The sender is also able to base distribution on the recipient's preferred channel, if required.

Documents to be distributed are placed in a file which is sent electronically to Nets, which sends or makes the document available through or in the customer's or recipients preferred channels. Some customers prefer traditional post, but an increasing number of recipients wish to take advantage of an electronic mail or digital distribution system. For the sender Nets will be the single point of contact. A single point of contact means that the sender does not have to decide on the medium through which the specific recipient wishes to receive documents. The sender only has to decide which channels to offer and the priority between the different distribution channels.

Nets Share comprises of a set of channels suited for efficient, secure and flexible distribution of information to recipients. 

This page contains a description of the features of Nets Share as well as a description of the implementation of the service. Each channel is described in further detail on separate pages see links below.

Associated Pages

Other relevant Pages are listed below.

Definitions

Table 1 provides a summary of relevant definitions used in this document.

​

Service ​​Desc​ription

This chapter provides a general description of how Nets Share works. A more detailed description can be found in Chapter 3 Functional and Technical Service Description.

General service description

Nets Share gives businesses the option of distributing information through several channels. All outgoing information is sent electronically to Nets, who makes the document available in the sender’s or recipient's preferred channel. Some customers prefer traditional post, but an increasing number wish to take advantage of an electronic mail system. A single point of contact for distribution simplifies the day-to-day tasks of the sender, as distributions are carried out via Nets Share to all channels. The sender receives a daily distribution report on the number of documents sent to the different channels. 

 The following output channels are supported:

• e-Boks.no
• e-Boks.dk
• e-Boks.se
• Print, delivered in Norway
• Print Nordic, delivered in Sweden and Denmark
• Return (returned to sender – unaddressable)

Signing In e-Boks

In the channel e-Boks you can perform an electronic signing of documents. If a document is marked for signing through the used document type e-Boks will start the E-Signing process for the document. E-Signing is a function in e-Boks and is further described in Channel description e-Boks.   

Value chain

Figure 1 shows the general process flow in Nets Share from a shipment file is dispatched all the way through the distribution engine via output channels to the final recipients. As can be seen from the illustration, there are five steps involved in the distribution of a shipment via Nets Share. The technical details associated with each step are described in the Functional and Technical Service Description.
«Figure 1. The process involved in distributing documents via Nets Share comprises five main activities»

General solution outline

Nets Share receives a shipment from the sender in the form of a zip file containing documents to a group of recipients. The solution offers the recipient several channels. It is up to the sender/recipient to determine which channel the documents are to be distributed through.

The sender uses Nets Share by transferring files to Nets. This is done by direct integration with an SFTP solution supplied by Nets.

The file being transferred (the Shipment) is a zip file consisting of an XML file (shipment.xlm) with metadata and an associated number of PDF documents which are to be distributed. The sender has the option of setting parameters in the shipment.xml file to manage the sender's own distribution preferences. An example of such a parameter is the option of managing the priority of the output channels (which output channels should be tried first and or skipped).

When the shipment file is placed in the correct folder on the SFTP and with the correct name format (netsshare_*.zip) it gets automatically forwarded to the Nets Share engine which then starts the next process which is the initial validation of the xml structure and content of the zip file. When the Shipment is initially validated in Nets Share according to the XSD (XML schema prepared for the Nets Share solution – See the example package) the file sender receives either an OK receipt (code 200) or a rejection receipt (code 400) with the reason for rejection if possible (see Get Started Step 1 for examples).

• ​​OK files (code 200) are sent through the system for further processing.
  
• ​Rejected Shipments are acknowledged as rejected and are not processed further in the system. And are not included in the distribution report. 
  

​OK files are further split into messages. A message consists of an XML containing metadata with an associated main PDF document. Nets distributes the document to the requested channel.  

Information about messages Confirmed or Rejected by the output channels is viewable in the daily distribution report. A distribution report is distributed every night at ~02.00 am. This report will contain information on documents distributed when we have received an OK confirmation from the distribution channel or a Rejection in the past 24 hours. For documents that are signed, a separate receipt zip file will be sent after signing or rejection containing a signed SDO and xml, along with an optional PADES, the distribution report for documents requiring signatures only confirmes that the document has been delivered. The signing confirmation as mentioned above gets sent in a separate zip file upon signing/rejection/timeout (see Get started Step 1 for examples).

Functional a​nd Technical Service Description   

This chapter describes the functional and technical requirements/solutions involved in the main processes outlined in Figure 1 above.

Sending and receiving files

SFTP (Secure File Transfer Protocol) is used to ensure secure exchange of files with senders. This technology provides security through an encrypted connection. Tool support is wide-ranging and good. Integration with the SFTP area itself is described in Get Started – Step 3.

General information

The sender is able to upload Shipments in the Inbound section and retrieve files in the sender's Outbound section of the mailbox (SFTP folders).  

When a Shipment has been validated, a validation receipt will be placed in the sender's mailbox with a status saying that the Shipment was OK or has been rejected, with a reason given. 

A shipment being marked as OK in the validation receipt is not to be confused with it being delivered to the recipient, but merely a confirmation of the Shipment being valid and from there attempted delivered to the appropriate output channel. To be sure, the message(s) in the Shipment have been delivered at the recipient, a distribution report is used, messages not deliverable will be placed in the final output channel "Return" to indicate that they were unable to be delivered without issues in the other channels.

Sender mailbox

As part of the integration with the SFTP area, directories will be created for shipment and receipt files to and from Nets Share.

In production, the Sender mailboxes, has the following structure for sending in files: pCOMPANY/Inbound/<Country><sender's business registration number> 

(e.g. pCOMPANY/Inbound/DK12345678 or pCOMPANY/Inbound/NOR11223344556)

The mailbox for receiving files in production has the following structure:
pCOMPANY/Outbound for receiving receipts, return files, subscription lists and distribution reports.

In tests, the sender mailboxes will have the following structure:
tCOMPANY/Inbound/<Country><sender's business registration number> for sending files and tCOMPANY/Outbound for receiving receipts, return files, subscription lists and distribution reports.

The Inbound area is used for files which are to be sent to Nets from the sender.

The Outbound area is used for files which Nets uploads to the sender. 

The Outbound files are deleted after 14 days if not by the customer when downloading them.

Shipment file from sender

Nets Share receives shipment files from the sender. The sender creates a Shipment file according to the prescribed format and structure and transfers it to the directory in the SFTP area in Nets according to the structure described above.

Once a Shipment has been placed in the correct mailbox, it is automatically transferred from the mailbox into the Nets Share system where it is;

1. Validated
2. Processed
3. Sent
4. Confirmed

 
 «Figure 2. The Shipment consists of a zip file containing a shipment XML and at least one PDF file»

Naming Shipments

A Shipment is a zip file containing PDF documents that are to be distributed to recipients and an XML file addressing the PDF documents. The XML file must describe all the documents which are to be distributed and contain all the required metadata to enable distribution.

The name of the Shipment zip file must have the prefix "netsshare" in line with the example below in lower case:  

netsshare_(filename chosen by sender).zip

(filename chosen by sender) in the description above is the optional part of the filename that is determined by the sender. The optional part of the filename is not validated against anything and duplicate values are allowed, but generally, it is recommended the filename match the shipment id from the shipment.xml)  

Naming PDF and XML files

shipment.xml, as the XML file must be called, contains several <message> elements. Each document for the recipient is described in a similar element.

The XML file is named as follows:  shipment.xml

The sender can freely decide names for the PDF files.

Each main PDF in the Shipment must be referred to in the XML with the following tag:
<filepath>document1.pdf</filepath>

The content of this tag is the filename of the PDF document.

Only the characters a-z, A-Z and numbers are permitted in the filename.

Please note that the content of the shipment.xml is case sensitive including the file name extensions.

Personal/Global attachment

In Nets Share it is possible to send pdf attachments to each main PDF document distributed. The attachments will follow the same layout requirements as standard documents in Nets Share – additional conditions are described below. As the title explains, the attachments are either individually related to each document, or added to all messages via the "Global attachment" tag, – The shipment must be specified to include either an individual (called local) or global attachment. See examples of attachment tags in Get Started Step 2.

Attachments can be used for all output channels, and for all <documentType> (material/document id's) in e-Boks.

The attachment is added in the attachment tag with the path attribute that is the filename for the attachment as it is in the zip file. As with the main document only PDF files are allowed.

In the shipment.xml file it is possible to have both global and local attachments. Global attachments are defined before the messages tag while local attachments are defined under the Document tag inside a Message tag. A global attachment applies to all messages in the shipment. A local attachment only applies to the specific Message it is a part of. You can have both global and local attachments in a message but the filenames must be different.

You can specify a short description to be displayed in e-Boks in the tag <eboks:attachment-description> Examples of attachments can be seen under Get Started – Step 2 where they are highlighted in light grey. 

Conditions:

Following conditions for using attachments in Nets Share applies:

Layout:
• A Maximum of 8 attachments to each document
• Same layout requirements as for standard documents in Nets Share
• Only PDF documents, preferably PDF1.6
• In local attachment, the tag <eboksAttachmentDescription> is mandatory when e-Boks is used as channel
• When bundling in print, all attachments will be printed with each main document
• The attachment file name must be different from the main document file name

Naming:
In e-Boks these filenames are reserved for attachments and cannot be used:
• attention.xml
• dkalafsendermetadata

 Screenshot of document received in e-Boks with attachment:

«Figure 3 Attachments will appear below the main document.»

Pricing:

e-Boks:
Will be charged by the sum MB size of the attachments plus the main document as if they were one, no extra fee for the attachment is otherwise applied.

Print:
Will be charged only with the cost of printed extra pages, and according to total weight of the envelop which might affect postage cost.

Example package

Nets has produced an example package containing examples of shipments, XSD files for validation and examples of receipts, signed documents and return files. The example package can be downloaded here.

Shipment limits

For practical reasons, Nets has imposed certain limits on the Shipment:

The Shipment cannot contain more than 10,000 messages (XML + PDF)
        *Nets recommends Shipments of 1-200 messages

The zip file cannot exceed a size of 2 GB.

If the number of PDF documents/size of the Shipment exceeds these limits, the Shipment must be divided into several parts.

PDFs to be distributed to e-Boks cannot exceed 10 MB. Where this is the case, the message will be sent via the next priority channel (e.g. print, return).    
          *Documents for signing must be under 1MB, but can have attachments of greater size

Validation/receipts, files from Nets.

Files from Nets to the sender will be placed in the Outbound directory for the sender and will be automatically deleted after ~14 days.

Validation

The Shipment is validated before it is processed further by the Nets Share systems. Validation includes the following controls:

• Duplicate control on the Shipment ID (shipmentID in shipment.xml must be unique).
• Validation against XSD to check XML structure, i.e. the zip file contains the shipment.xml file and this complies with the XML Schema definitions.
• Check that the PDF documents described in shipment.xml actually exist in the Shipment and that they comply with the PDF requirements (PDF/A version 1.4 or newer).
• Checks against the customer register, e.g. that the sender exists in the Nets Share register.
• Validation that there is at least one available channel.
• Validation that the same channel is not used more than once in the routing.
• Validation on number of attachments and total size

The result of the validation will always be communicated to the sender with an OK (code 200) or NOT OK (code 400) receipt so that the sender knows that the Shipment has been received by Nets Share.

Receipt

When the Shipment has been validated, a receipt is sent back to the sender. This receipt contains one of two possible messages:

1. The Shipment was validated OK
2. The Shipment did not comply with expectations.

The receipt is an XML file which will be placed in the sender's mailbox in the Outbound directory. The name of the receipt file depends on the Shipment filename.

If the sender sent a Shipment with the name netsshare_salary201118.zip to the mailbox pCOMPANY/DK12345678 the receipt file will be called: pCOMPANY_DK12345678_12345_netsshare_salary201118.zip.receipt.

<SFTP login name>_<country><Org. number>_<Unique serial number>_<FILENAME.zip.receipt> The receipt will usually be available in the Outbound directory within few minutes.

The table below contains a summary of the most common error messages. They all have the code 400 (rejection).

Receipt file for signed documents

If documents delivered through Nets Share to e-Boks is a document to be signed electronically in e-Boks, the shipment sender will receive a zip file containing signed documents or reject/timeout details. The file will contain information so the sender can identify the documents that have been signed or rejected/timed out. The file is a zip file that contains the following information:

• Shipment reference 
•  Message id
• Organization number of message sender
• Timestamp for when the document was signed, rejected or timed out.
• The signed document (the SDO file) or a rejection status with an optional "free text" reason.

The name of the receipt file for signed documents will have the following name structure.
signed_documents_YYYYMMDD_<hashkey>_<unique serial number for the signorder>.zip

example:
signed_documents_20210714_12a32427-cf12-41ba-9e23-65c62b324471_209359644.zip

See Get Started – Step 1 for examples of signed document receipts.   

Distribution to output channel

Nets Share supports a range of output channels and provides the option of managing distribution.

Channel selection

Shipments that have been validated OK will be processed by Nets Share by distributing the document to the below output channels.

• e-Boks NO, DK & SE
• Print NO
• Print DK and SE
• Return 

Standard sequence of distribution output channels

Nets Share has a standard sequence of available channels used for distribution.  The standard sequence is shown below:

1. e-Boks
2. Print
3. Return

Here Nets Share will start with the e-Boks channel and move on to the next channel until the document is either returned or confirmed by a prior channel.

Note: All channel selections require the necessary metadata to be contained in the shipment.xml, in order to enable the channel.

However, the sender is free to override the standard sequence by defining a required sequence in shipment.xml (see Get Started Step 2) or by defining it in the Nets Share customer register by contacting the support team.

Overriding the standard sequence of distribution channels

The sender is free to override the standard sequence by defining a required sequence in each shipment.xml. Override is carried out for each Message. 

An attempt will be made to distribute each PDF document according to the details contained in the shipment.xml. In the shipment.xml, the sender will be able to define precisely how each PDF document should be distributed to the recipient by indicating distribution parameters in the file format.  A PDF document may, for example, be addressed only to e-Boks (i.e. no print) with the last channel as return.

If return is not indicated as the last channel, the document will not be returned, but only labelled in the Nets system as not distributed; this can be seen in the distribution report as unaddressable. Hence it is always recommended that Return is places as the final channel even when using the routing override.

See how to override the standard sequence here.    

Return

Return is a "channel" used as the last output channel where documents that cannot be distributed for the sender via the other output channels are placed. This indicates that the message was unable to be delivered to the recipient.

Return can be selected as a channel by adding it in the shipment.xml or by using it in the standard sequence for distribution. An XML file is produced for each document that has not been distributed by the normal output channels and has reached the Return channel. The advantage is that the extra xml file *.return is placed immediately in the Outbound folder hence making it possible for the sender to see that the message has failed without having to wait till the distribution report is created at midnight.

Return Filename

The filename of the return file will have the following structure:

   pCOMPANY_<countrycode><organisation number><shipmentId><messageId>.return

The content of the XML file complies with the definition in the example package and contains the <message> element for the PDF document and the <shipmentInfo> element for the dispatch as described in shipment.xml. This is sufficient information for the sender to determine which PDF document has been returned.

Distribution report

The distribution report is an xml file containing information on documents distributed to recipients in an xml structure. The file is sent to the sender of shipments and contains a summary of how many messages are confirmed the last 24 hours to which channel and details for each document. The summary part comes first in the xml file and contains a statistic on how many documents are confirmed by each channel. After the summary there is a description of each message.

For each message the following information is present:

• ShipmentId
• MessageId
• MessageSenderId
• ProcessedDate (date confirmed or rejected by the given channel)
• Channel 

The Filename for the distribution report is formatted as below:

  <Shipment sender>+"_distributionreport_"+<YYYY-MM-DD>+".xml"

The date in the file name refers to the calendar date of which the messages/shipments contained in the file were processed by the chosen channel, e.g. e-Boks. The file is created at ~02:00am and includes information about messages processed the day before up until midnight. Please note that if a shipment is delayed by e-Boks and we receive the distribution information after midnight, the message/shipment will not be included in the following mornings distribution report, but in the one the day after instead (24hrs later). The same goes for the Print channel since they don't confirm the message before having printed the message, and this they have to do before 09:00am the day after receiving the messages, which means they occasionally print in the morning resulting in the message not appearing in the distribution report before 1½ day after sending. Hence, always wait 48 hours before contacting the support team if messages are missing.

The report is an xml file that is placed in the customers' "Outbound" folder.

Sample of the Distribution report xml:

<?xml version="1.0" encoding="UTF-8"?>
<distributionReport>
    <summary>
        <distributed channel="EBOKS">1</distributed>
        <distributed channel="PRINT">0</distributed>
        <distributed channel="PRINT_NORDIC">0</distributed>
        <distributed channel="EMAIL">0</distributed>
        <distributed channel="RETURN">2</distributed>
        <rejected>2</rejected>
    </summary>
    <messages>
        <message>
            <shipmentId>aaaaaa</shipmentId>
            <messageId>XXX</messageId>
            <messageSenderId>11111111</messageSenderId>
            <processedDate>2016-03-01</processedDate>
            <channel>EBOKS</channel>
        </message>
        <message>
            <shipmentId>bbbbbb</shipmentId>
            <messageId>YYY</messageId>
            <messageSenderId>11111111</messageSenderId>
            <processedDate>2016-03-01</processedDate>
            <channel>RETUR</channel>
        </message>
        <message>
            <shipmentId>bbbbbb</shipmentId>
            <messageId>YYY</messageId>
            <messageSenderId>11111111</messageSenderId>
            <processedDate>2016-03-01</processedDate>
            <rejectReason>returkode: 7, returtekst: Abonnementsforholdet findes ikke</rejectReason>
        </message>
        <message>
            <shipmentId>cccccc</shipmentId>
            <messageId>ZZZ</messageId>
            <messageSenderId>11111111</messageSenderId>
            <processedDate>2016-03-01</processedDate>
            <channel>RETUR</channel>
        </message>
        <message>
            <shipmentId>cccccc</shipmentId>
            <messageId>ZZZ</messageId>
            <messageSenderId>11111111</messageSenderId>
            <processedDate>2016-03-01</processedDate>
            <rejectReason>returkode: 70, returtekst: Afvist pga. fejl vedrørende signeringsbart dokument</rejectReason>
        </message>
    </messages>
</distributionReport>

The summary counts the number of messages for each channel and the rejected messages.

The rejected message will have the tag <rejectReason>. If the reason is not in the database we use the default message = 'Reason for failure is unknown'.
The other messages in the report will have the status = 'DISTRIBUTED_CONFIRMED'.                

XML fo​rmat

Generally, the XML structure is as shown in the figure below. There is one (and only one) <ShipmentInfo> element describing the Shipment. Then there is a <messages> element containing N number of <message> elements that comprise a recipient + document. 
 

«Figure 4. General description of XML schema»

Supported Nets Share XML versions

The XML format in Nets Share is under continuous development. Nets Share's goal is to be backwards compatible for up to three versions of the format. 

Currently, Nets Share XML Versions 1.3 up to 1.6 are supported, though only 1.6 supports the newest features such as realtime delivery, payments, dynamic signingtimeframe etc.. The format version is part of the namespace indicated in the <shipment xmlns> element in shipment.xml

Implementation ​Plan

This chapter provides a general description of the steps required by the customer and Nets to enable use of Nets Share. Implementation of Nets Share mainly consists of being able to produce Shipment files for Nets in the agreed standard format, and being able to read the Outbound files automatically. The process consists of seven defined activities and it is primarily the customer who manages progress. Nets' role is to create the customer in our systems and assist with testing. Nets' involvement in a standard implementation is estimated at five working hours.   

Review of testing and implementation process

«Figure 5 Implementation steps»
 
Before the implementation process begins, Nets recommends organizing a technical workshop (1). This can be held locally, by phone or skype. The purpose is for the customer and Nets to review the planned Nets Share solution, identify the required changes and preferred setup at e-Boks with the customer, and prepare a shared timetable for the implementation. In addition to setting clear shared objectives, efficient implementation is achieved by addressing ambiguities and special requirements at an early stage.

Before implementation can commence, Nets must have some required information in place, such as company information and, how the customer wishes to appear in e-Boks so that we are able to carry out the required configuration in our systems (2). This information is obtained from registration forms for Nets Share and e-Boks, which your Nets sales representative ensures is filled out and handed over to the (Nets Share) Support team.

The implementation itself is largely customer-driven. Nets will create the customer in the Nets Share environments (3) and assist in setting up the required file communication (4). From there it is up to the customer to plan the customer's sender system to produce Shipment files in the agreed format and with the functionality required by Nets (5). In our experience, the customer spends the most time on this activity.

Once the customer has the file communication up and running and organized the format, there will be a period (days or weeks) of testing carried out in conjunction with Nets (6). The purpose of this is to ensure that the integration is correctly set up and to check that documents can be distributed to the selected channels in the required manner. Nets has prepared standard testing steps, but is also able to adapt testing to customer requirements and procedures. Part of the testing involves provoking deviations so that deviation procedures and the receipt regime is understood. The test presupposes that format and communication is in place. If this should not be the case (e.g. major deviations in Shipment files), the test will be suspended and a new test done when the customer has addressed the deviations. In such cases, Nets is able to take a more active role in the process and, for example, provide more extensive format support.

When Nets and the customer agree that testing has completed, the customer is set up in the production system (7) and the first production Shipment is agreed. Nets will monitor this to ensure efficient start-up.

Nets has two separate virtually identical system environments – test and production. The main difference between these two is the server to which the Shipment is sent. This means that migrating a customer to the production setup is a very minor task.

Implementation process time perspective

The time spent on the implementation process highly depends on how long the customer spends on setting up communication and preparing the format (4)(5). The scope of these two activities primarily depends on the flexibility of internal systems and access to resources. 

In Nets' experience, by working efficiently, the implementation process should be completed (end-to-end) from start to production setup in approx. two calendar months.

Differences between the test and production environments

Nets has two separate system environments – test and production. The customer carries out all tests in the test environment and when these are approved, production date/runs are agreed with Nets.

The steps for setting up the test environment are identical to the ones for setting up production.  The customer will not be given access to the e-Boks demo environment, but Nets will be able to provide screenshots of what the distributed message looks like upon request. Personal identification number addressing allows the sender to freely select 'dummy' personal identification numbers in the test environment.    

«Figure 6 Nets has two 'physically' separated Nets Share environments – test and production»
 
PLEASE NOTE that IDs in e-Boks vary between the test and production systems, i.e.:

• e-Boks sender ID    
• e-Boks Material ID   

In other words, it is important to consider these when generating the first XML file in production after being in test.

General setup checklist   

The table below provides a general checklist with details for each previously described point.    

   Examples

For examples of the above-mentioned files please read the Get Started section and download the example package with the current XSD’s.
An example package is available for download here.

The package includes:
• Shipments (Shipment example (zip files) with shipment.xml and PDF's)
• Receipt directory (Examples of receipts – OK, duplicate, error)
• XSD (XML Schema definitions)