Implementing the Publication

Authorization

(Only applicable for Document Providers connected with their Document Senders through NSSO authorization server)

Only applications are allowed to publish messages to the e-Box. These are the valid scopes:

Scenario	Scope	Partition API check
Document Sender An application publishing for its own enterprise	scope:document:management:consult:ws-eboxrestentreprise:publicationsender	NONE
Service Provider An application publishing on behalf of another enterprise	scope:document:management:ws-eboxrestentreprise:eboxrepresentativepublication	/ebox/{enterpriseNumber}/hasMandate

For Service providers

Service providers applications are allowed to publish for the enterprises with which a mandate has been signed. You have to check if they have the scope scope:document:management:consult:ws-eboxrestentreprise:eboxrepresentativepublication and call the Partition web service to verify the mandate is valid:

1. Verify the scope scope:document:management:consult:ws-eboxrestentreprise:eboxrepresentativepublicationwith by introspecting the token
2. Extract the enterprise number (enterpriseNumber) by introspecting the token.
3. Verify the 'On-Behalf-Of-Enterprise-Number' header exists in the application http request.
4. Extract the 'On-Behalf-Of-Enterprise-Number' (mandataryEnterpriseNumber) header from the application http request.
5. Call the Partition web service /ebox/{enterpriseNumber}/hasMandate operation with enterpriseNumber, mandataryEnterpriseNumber and operation "publish". Verify the response "hasMandate" is true.

Event notifications Webhook

This is a mandatory feature for all document providers

Because some enterprise actions can affect the messages location or access rights, the Document Provider must implement the "{POST} /eventNotifications" endpoint. This endpoint is used as a webhook by the Event Notifications service to notify the Document provider something has happened for a given company. To understand the whole concept and how you should implement it, please consult the Event Notifications service page.

Routing rules

Apply routing rule for all new documents

This is a mandatory feature for all document providers

Every enterprise can manage its own e-Box with Routing rules. A routing rule will determine on which partition a new message should be routed. This is an important feature as the partition determines which users of the recipient enterprise can access the message. When a Document Sender sends a message to enterprise recipients, for each recipient, the Document provider must verify if a routing rule exists through the Partition web service. If it exists and matches the criteria of the message (see below for criteria information), the routing rule must be immediately applied to target the right recipient partition. A routing rule must be applied as soon as the message is published on the recipient e-Box. This process cannot be delayed.

Awareness of Routing rules updates

This is a mandatory feature for all document providers

As soon as an enterprise creates a new routing rule, the information is immediately propagated to all document providers through the Notifications mechanism. The main objective is to provide the Document Provider with the new ordered routing rules to be applied for the given recipient enterprise.

Determine the matching routing rule

There are three criteria allowed for a Routing rule. Each criterion is a mandatory property of a message:

1. messageTypeId: The message type identifier of the message.
2. senderApplicationId: The identifier of the application used to send the message.
3. senderOrganizationId: The enterprise number of the organization sending the message.

A routing rule contains at least one of the three criteria and has a priority. The routing rules are retrieved through the /ebox/{enterpriseNumber}/routingRules endpoint of the Partition web service . The response is already ordered by priority. Therefore, the Document Provider must loop to find the first routing rule matching the criteria if any. If there is no matching routing rule, the default target partition is GENERAL.

Thanks to the Notifications mechanism, the routing rules can be cached.

Handling Partition API unavailability

The Partition API is in the critical path. As mentioned above, it is important to take into account the potential existence of routing rules of each recipients. Therefore, if the Partition API is not reachable, you can not be sure which partition to target. If you use the default partition ('GENERAL') and a routing rule exists, it might lead to unwanted users having access to the document, which can lead to critical issues. In the other way, it would be quite impacting sending an HTTP 500 to your document senders.

Therefore, we have foreseen a specific partition technically called "PENDING_ROUTING" that is only available for enterprises administrators. Once the connection with the Partition API is restored, for any message that is STILL in the "PENDING_ROUTING" partition, you have to fetch the routing rules of the recipient and route it as defined above.

Document sender routing rules suggestions

(Out of scope for the Document Provider, for information)

The sender cannot decide on which partition of the recipient eBox the message should land. However, as the Document Sender is the best placed to know its message business context, the Document sender can propose a logical routing rule that we call a Routing rule suggestion. For this, the Document Sender, authenticated with NSSO authorization server, can interact with the Partition management web service. The suggestion will be proposed to the recipients of the message through the eBox enterprise user interface.

Summary

Order of the HTTP parts

The publication method needs to support any HTTP part order. One cannot expect for instance that the JSON part messageToPublish be the first HTTP part to be received. There are two reason for this:

• Several HTTP client do not give control on the order of the HTTP parts

• In order to support end to end streaming for the Document Sender.

  The messageToPublish can contain SHA-256 digests of the published documents. This means that the Document Sender might need to compute it. Computation of the digest requires to fully read the documents streams.

Note: The filename can contain encoded character. The filename must be decoded if it contains characters outside of the ISO-8859-1 charset (so french accents etc.).

In an end to end scenarios, the digest computation must occur during HTTP transfer to the Document Provider. The messageToPublish digests values cannot be known to the Document Sender before the Documents are fully sent to the Document Provider and the messageToPublish part can only be specified as last part of the exchange.

Multicast

(This is an optional feature)

This feature allows one single publication to be sent to many recipients and avoid duplicates.

Publishing

The first operation is to create the publication using the "{POST} /ebox/{enterpriseNumber}/publications" endpoint. The contract is pretty similar to the "{POST} /ebox/messages" endpoint used for the publication towards a single recipient. as a response, you'll return a publicationId required for the next operations.

Note that the Idempotency key concept is also applicable here. You can use the user's idempotency-key for the publication, and for each recipient added in the next operation, you concatenate it with the enterpriseNumber or the ssin if citizen.

Synchronous calls - targeting max 100 recipients

If the client targets a maximum of 100 recipients, you can support the synchronous {POST} /ebox/{enterpriseNumber}/publications/{publicationId}/addRecipients where recipients are directly provided in the Json request body. This service will directly publish the message to all recipients and return the status of all attempts. It is possible to use it multiple times on the same publicationId.

Asynchronous calls - targeting a large number of recipients

If a large number of recipients are targeted, you can support the long-running task {POST} /ebox/{enterpriseNumber}/publications/{publicationId}/multicastTasks where all recipients are provided in a CSV file. The process will run in background and directly return a Header "Location" containing the follow-up link with the created taskId.

Your Document Senders will then poll the {GET} /ebox/{enterpriseNumber}/multicastTasks/{multicastTaskId}/messagePublicationStatuses to retrieve the status of all publications.

For more endpoints and information, consult the Message Registry API.