User Manual

This page describes how to use the EbMS Adapter through its REST and SOAP interfaces. See EbMS Admin for installation and EbMS API for a method-level reference. The OpenAPI spec is available here.

Before you can exchange EbMS messages with another party you have to register a CPA that defines the contract between both parties (endpoints, certificates, retry policy). Optionally you can override CPA URLs and certificates per environment using URL Mappings and Certificate Mappings. After that you can exchange messages and track them through message events.

Manage CPAs

You can manage CPAs using the REST and SOAP CPAService.

1. validateCPA(cpa) — validate the CPA document before storing it
2. insertCPA(cpa, overwrite) — store the CPA; if overwrite is true an existing CPA with the same cpaId is replaced
3. getCPAIds() — list all registered cpaIds
4. getCPA(cpaId) — retrieve a stored CPA
5. deleteCPA(cpaId) — remove a CPA

Manage URL Mappings

You can override the endpoint URLs from a CPA per environment using the REST and SOAP URLMappingService. This is useful for routing the same CPA to a remote EbMS adapter through a Proxy Server or for testing purposes.

1. setURLMapping(urlMapping) — map a source URL (as defined in the CPA) to a destination URL
2. getURLMappings() — list all URL mappings
3. deleteURLMapping(source) — remove the mapping for source

Manage Certificate Mappings

You can override the SSL certificates from a CPA per environment using the REST and SOAP CertificateMappingService.

1. setCertificateMapping(certificateMapping) — map a source SSL certificate (as defined in the CPA) to a destination SSL certificate
2. getCertificateMappings() — list all certificate mappings
3. deleteCertificateMapping(source) — remove the mapping for source

Exchange Messages

The EbMS Adapter exchanges messages with remote EbMS adapters defined in a CPA, using the REST and SOAP EbMSMessageService. For large or binary payloads use the MTOM-enabled variant (see EbMS API).

Send a message

1. sendMessage(message) — submit the message to the EbMS Adapter; the adapter returns a generated messageId and asynchronously delivers it to the remote adapter according to the CPA's retry policy
2. getMessageStatus(messageId) — check the delivery status
3. Optional: resendMessage(messageId) — resend a message; a new messageId is returned

To be notified of delivery results without polling, configure an EventListener and consume Message Events.

Receive messages

When the remote adapter sends an EbMS message, the EbMS Adapter stores it with status RECEIVED. The application polls and processes it:

1. getUnprocessedMessageIds(messageFilter, maxNr) — list message IDs that match messageFilter and have status RECEIVED
2. getMessage(messageId, process) — retrieve the message; when process is true the message is marked PROCESSED and no longer returned by getUnprocessedMessageIds
3. Alternative: retrieve the message with process=false and call processMessage(messageId) after successful processing

Ping

You can verify connectivity and the CPA configuration with a remote adapter without sending business data:

1. ping(cpaId, fromPartyId, toPartyId) — performs an EbMS ping for the given CPA and party IDs

Message Events

Message Events let an application track the lifecycle of sent and received messages. They require eventListener.type = DAO.

1. getUnprocessedMessageEvents(messageFilter, eventTypes, maxNr) — list events matching messageFilter and eventTypes. Event types:
   • RECEIVED — a message was received
   • DELIVERED — a message was sent successfully
   • FAILED — a message returned an error while sending
   • EXPIRED — a message could not be sent within the attempts and time defined in the CPA
2. getMessage(messageId, process) — retrieve the message referenced by a RECEIVED event
3. processMessageEvent(messageId) — mark the event processed so it is no longer returned by getUnprocessedMessageEvents (and, for RECEIVED events, by getUnprocessedMessageIds)