Documentation

Documentation

Delivery contents #

This delivery consists of the following components:

  • SicsEMessagingServer.war - Java web application, with WebService interface to SICS eMessaging.
  • WSDL for the interface
  • ACORD documentation
  • A Java command line sample client

The individual components are described in greater detail in the respective sections of this document.

SICS eMessaging Server #

Only the parts of ACORD, 2007 specifically listed in this section are supported by the SICS eMessaging Server. Since version 4.5.1, SICS eMessaging Server can process several requests concurrently. The maximum number of concurrent requests can be specified in WEB-INF/web.xml by setting the SystemPoolInitialSize context parameter.

Call Service #

The interface offers basic support for the Call service described in ACORD, 2007. The Call service allows synchronous processing of an ACORD message. For details refer to the ACORD 2007 specification. This interface may not fully support all elements of the ACORD Call operation. It will attempt to process any request in accordance with the WSDL and the required elements as described in this document and the examples. Elements not described here or part of the examples will be ignored. Furthermore the emphasis of the SICS eMessaging server is on processing the attached ACORD message. As long as SICS is able to successfully unwrap the ACORD message, import and processing of the message will commence. In fact mandatory information in the SOAP request, such as sender and receiver are neither used nor validated by the system.

The basic flow of a Call request:

  • Client sends a Call request with an ACORD message attached
  • The SICS eMessaging Server will import the message and attempt to process it according to the SICS eMessaging rules.
  • A Call response is sent to the client, if the ACORD message could be completely processed, an ACORD Acknowledgement message will be attached to the response. If the ACORD message could not be completely processed, the response will in most cases contain one or more validation errors from the SICS eMessaging system.

Outbox Service #

The interface offers basic support for the Outbox service described in ACORD, 2007. The outbox must be used by the client to retrieve outbound messages from the server, and acknowledge successful reception of messages.

Retrieve implementation in SICS #

A call to the Retrieve service will search for the ACORD Acknowledgement message with status CREATED and the earliest archive timestamp and attach it to the response. If there are none, Retrieve will respond with SvcIndicCd = “retrieve_empty” and no attachment. If the Retrieve request attempts to retrieve a message specified by UUId, a SOAPFault will be given as ListOut is not supported.

StatusOut implementation in SICS #

For every successfully retrieved message, the client must invoke the StatusOut operation with the message’s UUId. SICS will change the status of the ACORD message with the UUId specified in the request to SENT. It will therefore no longer be returned from the Retrieve service.

The ListOut operation is NOT SUPPORTED by SICS #

In order to simplify synchronization and implementation, the ListOut service is not supported. It simply gives a SOAPFault if a client attempts to invoke it.

Outbox Message Flows #

Call response with acknowledgement #

flow_call_rsp_with_ack.svg

Empty Retrieve #

flow_empty_ret.svg

Retrieve with ACORD message in response #

flow_ret_with_acord_msg_in_rsp.svg

Limitations #

  • The SICS eMessaging server is based on SICS/Server and is therefore single threaded. If one request is being processed, subsequent requests must wait for the current request to complete. There is no built in failover support, so if there should occur a critical server failure, all pending requests will fail and must be resent.
  • All messages and ACORD message attachments are sent in clear text as MIME attachments. Neither security nor encryption is supported.
  • Only ACORD messages are processed, supporting documents are simply ignored
  • Only one ACORD message should accompany each request

Enabling SSL/TLS in Web server (optional) #

  • To establish a secure connection (HTTPS) between client and the web server, SSL/TLS need to be enabled on the web server. For detailed instructions follow specific web server documentation.

Installation instructions #

  • Set the SICS environment name in WEB-INF/web.xml if necessary. This is the same as in SICS API Server, refer to the SICS API Server installation document for more details.
  • Set the UserAuthorizationInterface init-param in WEB-INF/web.xml, if you plan to use it. This is the same as in SICS API Server, refer to the SICS API Server installation document for more details.
  • Set the UserExitImplementation init-param in WEB-INF/web.xml, if you plan to use it. This is the same as in SICS API Server, refer to the SICS API Server installation document for more details.
  • Uncomment the security-constraint element in WEB-INF/web.xml to configure the application to always use a secure connection. This ensures that any access via HTTP will automatically be redirected to HTTPS.
  • Uncomment the transportReceiver element in ‘WEB-INF/conf/axis2.xml’ to access HTTPS Protocol, or both HTTP and HTTPS protocols.
  • Install the web application SicsEMessagingServer.war in a Java servlet container.
  • The JNDI resource reference jdbc/sics must be mapped to a JDBC Datasource to a SICS database schema with SICS eMessaging enabled and configured.
  • If you are using WebSphere, enter in the WebSphere administration console and set the eMessaging Server application’s classloading option to “Classes loaded with application class loader first”.
  • Start the webapplication
  • Use the sample client / Java Axis to send requests. For other tools or platforms send SOAP requests to the URL: ${url to webapp}/wsdl/MyAcordMsgService.wsdl

Sample Client #

General #

A sample standalone client is included to demonstrate and document the SICS eMessaging server and how the SOAP messages can be created from ACORD messages using Java. The client contains Java Axis stubs for the web service and a simple command line application which shows how to use them.

Installation #

  • Copy the folder “sample client” to a suitable location.
  • Edit the file acord.client.properties in the subfolder conf, to set up URL to server etc.

Use #

  • Run the application with command: acord-client.bat <filename to ACORD message1, message 2 ...>
  • Various debug feedback information about what happens is displayed in the console.
  • Validations errors from the server if any are displayed.
  • If there is an ACORD Acknowledgement message in the response it will be stored on disk as: <UUId of the message>.xml

Example SOAP messages #

These simple examples show how to set up a message call based on the contents of the ACORD message and what response will be given under different circumstances. The examples are generated by the sample client and reflect the mapping actions provided by its utility classes.

NB! The ACORD and SOAP message contents have been slightly truncated to focus on the most important relationships between ACORD message and SOAP message.

Simple Request Example #

simple_req_example.svg

Response with Validation Errors #

rsp_with_validation_errors.svg

Response with Acknowledgement #

rsp_with_ack.svg

StatusOut to Acknowledge Reception of Message #

statusout_to_ack_reception_of_msg.svg

Retrieve request #

retreive_req.svg

Retrieve Response with ACORD Message #

retreive_rsp_with_acord_msg.svg

References #

ACORD, 2007 #

ACORD. (2007, December). ACORD MESSAGING SERVICE XML SPECIFICATION AND SOAP IMPLEMENTATION GUIDE VERSION 1.5.1