In order to be a Document Provider one MUST implement a Message Registry Service and Register that service on the Provider Registry Service. This service MUST follow the e-Box Message Registry open API Spec
Introspect of an e-Box Enterprise Oauth Token
The DP methods are secured by Oauth2 tokens. Introspecting these token can be tricky since the introspect endpoint security is quite high using oauth itself to secure the call to the
The introspect endpoint return several information, the most important being the organization CBE which is the unique identifier of an organization and of it's e-Box.
Among the endpoints below, the back channel is the authentication endpoint that gives you your token.
Here is an example introspect payload.
Proper Oauth2 treatment of the token will not be described here as it is done out of the box by most Oauth client and is documented in the Oauth Specification. However here are some pointers
activeneeds to be checked, if false the token is not acceptable
scopeneed to be checked based on the endpoint
principalAttributes[‘urn:be:fgov:kbo-bce:organization:cbe-number’]contains the CBE number which identifies the e-Box of the user. That CBE number is not necessarily in 10 digits format and so you may need to add a prefix with as many 0 as needed to obtain the 10 digits format. In the e-Box services, CBE numbers must be encoded in 10 digits.
The following resources expand a bit on the subject:
Scopes and endpoints mapping
The e-Box Enterprise Document Providers endpoints are secured by the following scopes:
scope:document:management:consult:ws-eboxrestentreprise:summaryownebox: Give access to the
/eboxresource of identified user
scope:document:management:consult:ws-eboxrestentreprise:summaryallebox: Give access to the
/eboxresource of any user.
scope:document:management:consult:ws-eboxrestentreprise:messagesfull: Give access to the
/ebox/message/**resource of identified user.
scope:document:management:consult:ws-eboxrestentreprise:referencedata: Give access to the
Integration with the Portal
The e-Box Enterprise Portal will be the primary consumer of the Document Provider. Usage by the portal has some particularities that are worth nothing.
Resources used by the Portal
From all of the API endpoints, only a few are actually used by the portal.
/ebox/messages: This is the main method being used by the Portal. It provides all the information provided by all of it's sub resources making direct calls to sub resources useless or rare.
/ebox/messages/<id>/attachments/<attachmentId>/content: This method is used to get the attached documents
/ebox/messages/<id>: This method is used when displaying a message details and is therefore not used allot
/referenceData/senderApplication/<id>: This method is called for every single message displayed in e-Box.
/referenceData/senderOrganization/<id>: This method is called for every single message displayed in e-Box.
/referenceData/messageType/<id>: This method is called for every single message displayed in e-Box.
Note: Integration to portal in ACC is allowed when this minimal set of resources has been implemented.
totalItems are required in the following Json Schemas described in the API:
If there is no item, do not put null as value for the item property but a void list.
HTTP Cache headers guidelines
In order to offer the best possible user experience cache control headers MUST be used on some the
/referenceData/** endpoints. These endpoints are heavily used by the e-Box Enterprise UI which itself does not use caching so to not impose latency in data updates on the DP.
The following endpoints are MUST have significant cache control headers.
We recommend a 2 day fixed cache with non-blocking background refresh, but more advanced options can be chosen.
Cache-Control: public, no-transform, proxy-revalidate, max-age=86400
TranslatedString OpenApi contract allows for 0 to 3 language to be specified: nl,fr,de.
However for proper integration with the portal, all 3 values must be provided. If some values are not available they need to be default by the DP, preferably with another language value.
Message List endpoint
The Message List endpoint is the single most important endpoint of e-Box. It gives access to all information of all Messages with the notable exception,of the attachments binary content.
The resource also offers several search capabilities which are all documented in the specification. All search criteria are to be applied in conjunction, meaning all messages returned MUST match all criteria provided.
Criteria which match no message should return a 200 HTTP status with an empty list of messages. This even if the case when
incoherent criteria are provided (like a receivedAfter=2060-03-05). 400 status code MUST and only can be returned with syntactically
incorrect criteria or if
q is provided without
Text search feature
The Text search feature allows substring search in all visible textual information related to a message in the language of the user. Search excludes research in the document or body content themselves.
The text search is driven by the
qlang fields, which must both be provided for the text search to work.
qlang values are:
Note: API specification at the time of writing do not contain the enum of values, this will be addressed in subsequent versions at which point the list provided here will be removed
q parameter represent a portion of text to be found in all "visible textual information". The following API fields are searched
- values of business data (businessDataList.values)
Note: All of the searchable fields are TranslatedString, this is why
qlang has to be specified,
to know to which language of TransateldString it the
q parameter is to be applied
The values searched by
q have the following extra properties
- Case is to be ignored
- Accents are to be ignored
Given the following value present in one of the aforementioned fields (the title for instance), the following searches will detect the message:
- Value in searchable field:
This is some random with Special cases like épinards and François, ok?
me rando: found
SOME RAND: found
ok?This is: not found
This some random: not found
Testing on eboxenterprise.be
e-Box Enterprise provides a unified view of all Document Providers through the https://eboxenterprise.be website. As a Document Provider you are required to validate your implementation in this interface.
There are two ways to test a Document Provider on this interface.
1) Using the wwwacc.eboxenterprise.be website which is part of a distinct environment as production. This means that the Authorization server is different from the one in production, and that production data cannot be showed. 2) Using the in app testing features called 'Local DP' which allow secure testing directly in production. A Local DP is only configured in your browser so it will have no impact on other users of the application.
We will describe how to use the more powerful and secure Local DP approach . This is however to be considered as an experimental feature so your feedback is very welcome. If things goes as planned, it could fully replace the first approach.
In oder to test using the second approach:
4) Refresh your browser
You should see a very different page with a watermark and a big red message indicating that you have activate a development feature. The DP will now be configured in your local storage so you will not have to reconfigure it.