Message Registry Service - Consultation

Mandatory implementation

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 3.0 or above. The consultation part of the API are operations containing one of the following tags in the specifications:

Messages
ReferenceData
Statistics
Reply

The reply operation is considered to be in the consultation part of the Message Registry since Document Consumers and users with a consultation right can reply to messages.

The implementation of operations about consulting the list of messages, message details, downloading an attachment content, reference data and statistics are mandatory. The implementation of operations about replies, message actions, message templates, paymentData and structuredData are optional depending on the features that the Document Provider wishes to implement. Optional operations contain the description "The implementation of this operation is optional" in the API. The list of messages should be returned ordered by the publication date in descending order (most recent first).

Introspect of an e-Box Enterprise OAuth Token

The Document Provider methods are secured by OAuth V5 tokens. Introspecting these tokens can be tricky since the introspect endpoint security is quite high using OAuth itself to secure the call to the /introspect endpoint. The introspect endpoint returns some information, the most important being the organization enterprise number issued by CBE which is the unique identifier of an organization and of its e-Box. Among the endpoints below, the back channel is the authentication endpoint that gives you your token.

	ACC
Back channel	https://services-acpt.socialsecurity.be/REST/oauth/v5/token
Introspect	https://services-acpt.socialsecurity.be/REST/oauth/v5/introspect
Audience	https://services-acpt.socialsecurity.be/REST/oauth/v5/token
	PROD
Back channel	https://services.socialsecurity.be/REST/oauth/v5/token
Introspect	https://services.socialsecurity.be/REST/oauth/v5/introspect
Audience	https://services.socialsecurity.be/REST/oauth/v5/token

Here is an example of introspect payload of a human user connected to the e-Box Enterprise portal.

{
    "active": true,
    "client_id": "documentmanagement:publication:eboxenterprise:client_implicit",
    "token_type": "access_token",
    "sub": "urn:be:smals:um:identifier:ENT_CBE(BECBE=406798006):QUAL_EMP_NOSS(BENOSS=000370539):USER_INDIVIDUAL(BESSIN=79072300048)",
    "aud": "document:management:consult:ws-eboxrestentreprise documentmanagement:publication:eboxenterprise security:authorization:oauth:userinfo",
    "iss": "https://oauth-v5.acpt.socialsecurity.be",
    "jti": "i1v18l327gktaad04vuetqnrso",
    "iat": 1563882772,
    "exp": 1571658772,
    "nbf": 1563882712,
    "scope": "openid profile scope:document:management:consult:ws-eboxrestentreprise:partitionuser scope:ebox:enterprise:profile",
    "principalAttributes": {
        ...
        "urn:be:fgov:kbo-bce:organization:cbe-number": ["0406798006"],
        "urn:be:smals:env:user-type": ["ENTERPRISE"],
        "urn:be:fgov:person:ssin": ["79072300048"],
        ...

    }
}

Here is an example of introspect payload of a Document Consumer application.

{
    "active": true,
    "client_id": "my:ebox:enterprise:dp:client",
    "token_type": "access_token",
    "sub": "my:ebox:enterprise:dp",
    "aud": "document:management:consult:ws-eboxrestentreprise documentmanagement:ebox:enterprise:federation-rest",
    "iss": "https://oauth-v5.acpt.socialsecurity.be",
    "jti": "i1v18l327gktaad04vuetqnrso",
    "iat": 1563882772,
    "exp": 1571658772,
    "nbf": 1563882712,
    "scope": "scope:document:management:consult:ws-eboxrestentreprise:documentconsumer scope:documentmanagement:ebox:enterprise:federation-rest:registry",
    "principalAttributes": {
        ...
        "urn:be:fgov:kbo-bce:organization:cbe-number": ["0406798006"],
        "urn:be:smals:env:user-type": ["ENTERPRISE_EXPEDITOR"],
        "urn:be:smals:uam:system:calling-application-urn": ["my:ebox:enterprise:dp"],
        ...

    }
}

Proper OAuth2 treatment of the token will not be described here as it is done out of the box by most OAuth clients and is documented in the OAuth Specification. However here are some pointers:

active needs to be checked, if false the token is not acceptable
scope needs to be checked based on the endpoint. See the section Scopes below.
principalAttributes[‘urn:be:fgov:kbo-bce:organization:cbe-number’][0] contains the CBE number, known as the enterprise number which identifies the e-Box of the user. That enterprise 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, enterprise numbers must be encoded in 10 digits.

The following resources expand a bit on the subject:

Java Example of an Introspect

More detailed information can be found on the OAuth cookbook.

Scopes

All of the scopes described bellow gives access to the methods containing one of these tags in the API:

Messages
ReferenceData
Statistics
Reply

If the user has the scope scope:document:management:consult:ws-eboxrestentreprise:documentconsumer then the user is actually an application onboarded as a Document Consumer and thus can consult all the messages in all partitions of the enterprise.

Else, the user must have at least one of the following scope :

scope:document:management:consult:ws-eboxrestentreprise:eboxresponsible
scope:document:management:consult:ws-eboxrestentreprise:eboxenterpriseadmin
scope:document:management:consult:ws-eboxrestentreprise:eboxmandataryadmin
scope:document:management:consult:ws-eboxrestentreprise:eboxenterpriseuser
scope:document:management:consult:ws-eboxrestentreprise:eboxmandataryuser
scope:document:management:consult:ws-eboxrestentreprise:partitionuser (deprecated soon)
scope:document:management:consult:ws-eboxrestentreprise:messagesfull (deprecated soon)

and the Partition web service must be used in order to check which partitions the user can consult.

The reason to have several scopes for the case where you have to consult Partition web service is to help that web service itself to compute the access to partition.

User consultation rights check on Partitions

Because partitions have their own human user access management, some additional checks must be done. There is no additional check to perform for application users, also called Document Consumers, as they performed an administrative onboarding and thus have access to all the messages in their e-Box. You can observe in the introspect JWT examples in this page the differences between the introspect result for a token from human user and the one for an application user (Document Consumer application).

For Document Consumer application users

Document Consumers applications have access to all messages of their enterprise. You still have to check if they have the scope scope:document:management:consult:ws-eboxrestentreprise:documentconsumer and also if the request is not about a message in someone else's e-Box.

For human users

For message consultation, statistics and reply, you need to use the Partition web service in order to get the list of partitions that the human user can consult or to check if the user has a consultation right on a specific partition. The scope needed to consult any user's right in the Partition service is scope:document:management:consult:ws-eboxrestentreprise:documentprovider. See the Partition web service documentation page for more information about the service and its API.

The Document Provider needs to record the recipient partition of a message. By default, the message is in the GENERAL partition. Below are descriptions for each use case that the Document Providers need to consult the Partition service.

The user gets all the messages

If the user performs a GET /ebox/messages request with any parameters but without specifying a recipientPartition, the Document Provider needs the list of partitions that the user can consult. The request to send to the Partition service is GET /ebox/{ebox enterprise number}/userPartitionRights?userType=human&userId={user SSIN}. The service then returns a list of objects containing a partition identifier and the user rights on the partition. The messages to return to the user are all the messages that are in the partitions in the list returned by the Partition service for which the consult boolean is set to true. The GENERAL partition is the default partition. The publications done without specifying the partition are considered to be in the GENERAL partition.

The user gets statistics

If the user performs one of the GET /ebox/messages/statistics/* requests without the partition parameter, the scenario is the same as above except that the count is returned instead of the messages. The purpose is to get a count based on the messages that the user can consult. If the Document Provider does not support messages with actions of type requiredActionToConfirm, then the Document Provider can return 0 to the request GET /ebox/messages/statistics/withActionRequired without consulting the Partition service. If the Document Provider does not support registered mails, then the Document Provider can return 0 to the request GET /ebox/messages/statistics/registeredMails without consulting the Partition service.

The user moves messages

If the user performs the POST /ebox/messages/changePartition request, then the Document Provider needs to check if the user has the right to consult the messages that the user wants to move for security reasons. It is not required to check if the user has a right on the target partition. The Document Provider also needs to check if the target partition exists.

The Document Provider needs to get the list of partitions that the user can consult. The request to send to the Partition service is the same as mentioned in the paragraph about retrieving messages: GET /ebox/{ebox enterprise number}/userPartitionRights?userType=human&userId={user SSIN}. Then for all the messages in the request from the user, the Document Provider checks if these messages are in a partition that the user can consult. The message IDs in the request from the user are not necessarily in the same partition. If the user can effectively consult all messages, then the Document Provider can change the recipient partition in its database. If there is at least one message that the user cannot consult, then no messages can be moved and the Document Provider returns an error HTTP 403.

To check if the target partition exists, The request GET /ebox/{enterprise number}/partitions returns the list of existing partitions in the recipients e-Box.

The user hides or unhides messages

If the user performs the POST /ebox/messages/changeVisibilityrequest, then the scenario is the same as when moving messages.

The user filters the messages list on a partition

If the user performs a GET messages request with a filter on recipientPartition, the Document Provider should check if the user has the consultation right on the partition. The request to send to the Partition service is GET /ebox/{ebox enterprise number}/userPartitionRights?userType=human&userId={user SSIN}&partitionId={recipient partition ID}. If the Partition service returns an object and the consult boolean in this object is true, then the Document Provider can provide the data to the user, otherwise it returns an error HTTP 403.

The user consults the message details

If the user performs one of these requests

GET /ebox/messages/{message ID}
GET /ebox/messages/{messageId}/body
GET /ebox/messages/{messageId}/paymentData
GET /ebox/messages/{messageId}/structuredData

The Document Provider should check if the user has the consultation right on the partition that contains the messages. The scenario is then the same as mentioned in the paragraph about moving messages. The request to send to the Partition service is GET /ebox/{ebox enterprise number}/userPartitionRights?userType=human&userId={user SSIN}&partitionId={recipient partition ID}. If the Partition service returns an object and the consult boolean in this object is true, then the Document Provider can provide the data to the user, else it returns an error HTTP 403. The implementation of the operations to get body, paymentData and structuredData are optional if the Document Provider does not support these functionalities. The Document Provider does not need to check rights for a feature that it does not support and can return an error HTTP 404 directly.

The user downloads the attachment content

If the user performs a GET /ebox/messages/{message ID}/attachments/{attachment ID}/content request, the Document Provider should check if the user has the consultation right on the partition that contains the messages. The scenario is then the same as above.

The user replies

If the user performs a POST /ebox/messages/{messageId}/reply request, the Document Provider should check if the user has the consultation right on the partition that contains the parent message which is being replied to. The scenario is then the same as above. If the message is not actually marked as able to reply to, indicated by the isReplyAuthorized property in the Message object, then the Document Provider can immediately return an error HTTP 400 without performing any additional checks.

The user confirms or unconfirms the message action execution

If the user performs a PATCH /ebox/messages/{messageId}/actions/{messageActionId} request, the Document Provider should check if the user has the consultation right on the partition that contains the message. The scenario is then the same as above.

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 noting.

Resources used by the Portal

From all of the API endpoints, these are actually used by the portal.

/ebox/messages: This is the main method being used by the portal. The portal adds a pagination parameter with a pageSize of 10, 20, 50 or 100.
/ebox/messages/<id>: This method is used when displaying the message details and is therefore not used as frequently.
/ebox/messages/<id>/attachments/<attachmentId>/content: This method is used to get the attached documents. When sending the filename as header, make sure you escape/replace non ASCII characters as not all of them are supported in HTTP Headers.
/refData/senderApplication/<id>: This method is called for every single message displayed in e-Box and cached.
/refData/senderOrganization/<id>: This method is called for every single message displayed in e-Box and cached.
/refData/messageType/<id>: This method is called for every single message displayed in e-Box and cached.
/refData/senderApplication: This method is also called and cached.
/refData/senderOrganization: This method is also called and cached.
/refData/messageType: This method is also called and cached.
/ebox/messages/statistics/nearlyExpired: This method is called to generate an alert. It is called once per connexion.
/ebox/messages/statistics/withActionRequired: This method is called to generate an alert. It is called once per connexion.
/ebox/messages/statistics/registeredMails: This method is called to generate an alert. It is called once per connexion.
/ebox/messages/changeVisibility: This method is called when the user selects messages and clicks on the hide button.
/ebox/messages/changePartition: This method is called to move messages between partitions in the same e-Box.

Note: Integration to portal in ACC is allowed when this minimal set of resources has been implemented. See the page Message Registry Service - Consultation test scenarios to get more details and scenarios that can help to do a set of validation tests.

These endpoints are also called depending on supported feature :

/ebox/messages/{messageId}/body: If the Document Provider supports messages with a textual body as message content.
/ebox/messages/{messageId}/reply: If the Document Provider supports messages that can be replied to.
/ebox/messages/{messageId}/actions/{messageActionId}: If the Document Providers support messages with action required.

HTTP Cache headers guidelines

In order to offer the best possible user experience cache control headers MUST be used on some the /refData/** endpoints. These endpoints are heavily used by the e-Box Enterprise UI which itself does not use caching so as not to impose latency in data updates on the Document Provider.

The following endpoints are MUST have significant cache control headers.

/refData/messageTypes/*
/refData/senderOrganization/*
/refData/senderApplication/*

We recommend a 2 day fixed cache with non-blocking background refresh, but more advanced options can be chosen.

e.g: Cache-Control: public, no-transform, proxy-revalidate, max-age=86400

LocalizedString

LocalizedString OpenApi contract allows for 0 to 3 language to be specified: nl, fr and de.

However for a proper integration with the e-Box Enterprise portal, all 3 properties must contain a value. If some values are not available in a specific language, the available language should be returned for the other possibilities by the Document Provider. For example, if the Document Provider supports only one language per message, then the same text must be put as value for the three properties. The purpose is to display a text to the user even if the user changes the languages in the portal.

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 API. 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 is the case even if incoherent criteria are provided (like a receivedAfter=2060-03-05). HTTP 400 status code MUST and only can be returned with syntactically incorrect criteria or if q is provided without qlang.

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 q and qlang fields, which must both be provided for the text search to work. Possible qlang values are: fr,nl, de

Note: API specification at the time of writing does not contain the enum of values, this will be addressed in subsequent versions at which point the list provided here will be removed

The q parameter represents a portion of text to be found in all "visible textual information". The following API fields are searched based on q and qlang.

- Message: - subject - values of business data (businessDataList[].values[]) - forTheAttentionOf: - ssin - label - Application: - name - description - Organization: - name - description - MessageType: - name - description

Note: All of the searchable fields are LocalizedString, this is why qlang has to be specified: To know to which language of LocalizedString 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

Example:

Given the following value present in one of the aforementioned fields (the subject 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?
some: found
me rando: found
ok?: found
François: found
Francois: found
epinards: found
ép: found
SOME RAND: found
ok?This is: not found
This some random: not found

The CORS is a browser mechanism which enables controlled access to resources located outside of a given domain. The Document Provider has to accept these origins:

Origins to accept :

Environment	URLs
ACC	https://wwwacc.app.eboxenterprise.be https://eboxenterprise-channel-a.acc.socialsecurity.be https://eboxenterprise-channel-b.acc.socialsecurity.be https://eboxenterprise-channel-c.acc.socialsecurity.be https://eboxenterprise-channel-c.acc.ext.socialsecurity.be https://eboxenterprise-channel-b.acc.ext.socialsecurity.be https://eboxenterprise-channel-a.acc.ext.socialsecurity.be https://eboxenterprise-channel-c.acc.pub.socialsecurity.be https://eboxenterprise-channel-b.acc.pub.socialsecurity.be https://eboxenterprise-channel-a.acc.pub.socialsecurity.be
PRD	https://app.eboxenterprise.be https://eboxenterprise-channel-a.socialsecurity.be https://eboxenterprise-channel-b.socialsecurity.be https://eboxenterprise-channel-c.socialsecurity.be https://eboxenterprise-channel-c.prd.ext.socialsecurity.be https://eboxenterprise-channel-b.prd.ext.socialsecurity.be https://eboxenterprise-channel-a.prd.ext.socialsecurity.be https://eboxenterprise-channel-c.prd.pub.socialsecurity.be https://eboxenterprise-channel-b.prd.pub.socialsecurity.be https://eboxenterprise-channel-a.prd.pub.socialsecurity.be https://www.staging.eboxenterprise.be

Environment

URLs

ACC

PRD

Some HTTP headers need to be added in the response. The origins should be put as value for the Access-Control-Allow-Origin header.

Access-Control-Allow-Origin: (see table above)
Access-Control-Allow-Methods: GET, HEAD, POST, PUT, DELETE, TRACE, OPTIONS, PATCH
Access-Control-Allow-Headers: Content-Type, Authorization, Accept, Accept-Language, If-None-Match, If-Modified-Since, Location
Access-Control-Expose-Headers: Location

Testing on eboxenterprise.be

e-Box Enterprise provides a unified view of all Document Providers through the eboxenterprise.be website. As a Document Provider you are required to validate your implementation in this interface.

You can test a Document Provider on this interface using the in-app testing feature called 'Local DP'. A Local Document Provider is only configured in your browser so it will have no impact on other users of the application. In order to test using the second approach:

log into the interface of your choice: acc or prd
Open the javascript console (by pressing F12 on most browsers)
Add your Document Provider using the following javascript code

app.addDocumentProviders({'url':'https://mydevelopmentdp.com/pathToRoot',name:'test_mydp', version:'3.0.0', id:'test_mydp'})

Refresh your browser

You should see a very different page with a watermark and a big red message indicating that you have activated a development feature. The Document Provider will now be configured in your local storage so you will not have to reconfigure it.

If you want to remove the configuration use the following javascript code

app.resetDocumentProviders()

Mandatory implementation​

Introspect of an e-Box Enterprise OAuth Token​

Scopes​

User consultation rights check on Partitions​

The user gets all the messages​

The user gets statistics​

The user moves messages​

The user hides or unhides messages​

The user filters the messages list on a partition​

The user consults the message details​

The user downloads the attachment content​

The user replies​

The user confirms or unconfirms the message action execution​

Integration with the Portal​

Resources used by the Portal​

HTTP Cache headers guidelines​

LocalizedString​

Message List endpoint​

Text search feature​

Cross-origin resource sharing (CORS)​

Testing on eboxenterprise.be​