Asynchronous message request/response

Message request header

All header content is under traceHeader element that contains traceIdentifier element with tracing information of incoming message.

TraceIndentifier parameters

Parameter	Type	Description	Mandatory
applicationID	string	Identification of source application.	Y
timestamp	dateTime	Timestamp of sent request.	Y
correlationID	string	Used to track calls from the service consumer to the API. This parameter is free text, unique value (e.g. UUID), generated by the caller. It is the responsibility of the application to generate a unique value and pass it during each call to the API. Unique identifier (at least for specific application) serves for pairing asynchronous request/response messages.	Y
processID	string	Used to track calls connected to one process (e.g. one process is "creating new customer" and it means calling creating customer, then activating him etc.) This parameter is free text, unique value (e.g. UUID), generated by the caller. It is the responsibility of the application to generate a unique value and pass it to all calls of one process.	N

SOAP example:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:com="http://openhubframework.org/ws/Common-v1" xmlns:hel="http://openhubframework.org/ws/HelloService-v1">
   <soapenv:Header>
      <com:traceHeader>
         <com:traceIdentifier>
            <com:applicationID>APPL001</com:applicationID>
            <com:timestamp>2013-05-21T10:33:58.147+02:00</com:timestamp>
            <com:correlationID>${=java.util.UUID.randomUUID()}</com:correlationID>
            <!--Optional:-->
            <com:processID>process001</com:processID>
         </com:traceIdentifier>
      </com:traceHeader>
   </soapenv:Header>
   <soapenv:Body>
      <hel:asyncHelloRequest>
         <hel:name>OpenHub team</hel:name>
      </hel:asyncHelloRequest>
   </soapenv:Body>
</soapenv:Envelope>

Validation of trace identifier from trace header

It's good practice to use validation functionality of allowed values in applicationID. This value is used for example in GUI Admin, auto confirmation delegation etc. For that we only have to register custom implementation of ExternalSystemIdentifierValidator interface. We can have an unlimited number of these implementations.

@Service
public class CenExternalSystemIdentifierValidator implements TraceIdentifierValidator {
    @Override
    public boolean isValid(TraceIdentifier traceId) {
        return EnumUtils.isValidEnum(ExternalSystemEnum.class, traceId.getApplicationID());
    }
}

SOAP example of failed response for sync operation:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <SOAP-ENV:Fault>
         <faultcode>SOAP-ENV:Server</faultcode>
         <faultstring xml:lang="en">
				E120: the trace identifier does not contain allowed values (ValidationIntegrationException: the trace identifier 
				'applicationID=ERP,timestamp=2013-09-27T10:23:34.698+02:00,correlationID=da793349-b486-489a-9180-200789b7007f,processID=process123' is not allowed)
         </faultstring>
         <detail>
            <errorCode xmlns="http://openhubframework.org">E120</errorCode>
         </detail>
      </SOAP-ENV:Fault>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

SOAP example of failed response for async. operation:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <asyncHelloResponse xmlns="http://openhubframework.org/ws/HelloService-v1" xmlns:ns2="http://openhubframework.org/ws/Common-v1">
         <confirmAsyncHello>
            <ns2:status>FAIL</ns2:status>
            <ns2:additionalInfo>
				E120: the trace identifier does not contain allowed values (ValidationIntegrationException: the trace identifier 
				'applicationID=ERP,timestamp=2013-09-27T10:23:34.698+02:00,correlationID=da793349-b486-489a-9180-200789b7007f,processID=process123' is not allowed)
			</ns2:additionalInfo>
         </confirmAsyncHello>
      </asyncHelloResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Message response

There is synchronnous response that indicates if input message was correctly saved into message queue for next processing.

SOAP example of successful response:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <asyncHelloResponse xmlns="http://openhubframework.org/ws/HelloService-v1" xmlns:ns2="http://openhubframework.org/ws/Common-v1">
         <confirmAsyncHello>
            <ns2:status>OK</ns2:status>
         </confirmAsyncHello>
      </asyncHelloResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

SOAP example of failed response:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <asyncHelloResponse xmlns="http://openhubframework.org/ws/HelloService-v1" xmlns:ns2="http://openhubframework.org/ws/Common-v1">
         <confirmAsyncHello>
            <ns2:status>FAIL</ns2:status>
            <ns2:additionalInfo>E106: error during saving asynchronous message into storage (RuntimeException: some error)</ns2:additionalInfo>
         </confirmAsyncHello>
      </asyncHelloResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

It's good practice to use specific response for one request and not one common response for all requests: asyncHelloResponse -> asyncHelloRequest

If error occurred during incoming message processing (ThrottlingExceededException and StoppingException at this moment) then fault response is generated (identical for synchronnous message). Fault response contains error description and error code for clear indentification.

SOAP example with fault:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <SOAP-ENV:Fault>
         <faultcode>SOAP-ENV:Server</faultcode>
         <faultstring xml:lang="en">E117: Access is denied - there is no required authorization role (AccessDeniedException: Access is denied)</faultstring>
         <detail>
            <errorCode xmlns="http://openhubframework.org">E117</errorCode>
         </detail>
      </SOAP-ENV:Fault>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>