Asynchronous vs Synchronous

There has been confusion on the two different "modes" that can be used to submit requests to the EasyLink Messaging system.

Synchronous Mode

The EasyLink Messaging API can be used in "synchronous" mode. In synchronous mode, there is a single request/response pair for every transaction with the response containing the results from processing the request.

For example, the request may contain a JobSubmitRequest in the SOAP Body, in which case the result would contain a JobSubmitResult containing the job id of the job that was created (note that the job itself has not completed - just the submission of the job to the delivery system.) When the client gets the response, all API processing of the request is complete.

Below is a sample Synchronous Mode JobSubmit Request (please note this request has been manually altered for formatting purposes and the encoded documents have been truncated. To find working XML please search the site for XML Sample)

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Header>

<ReceiverKey>http://test2api.pgiconnect.com/soap/sync</ReceiverKey>

<RequesterID>REQUESTER</RequesterID>

<Password>PASSWORD</Password>

</XDDSAuth>

</Authentication>

</Request>

</soap:Header>

<soap:Body>

</Document>

<Filename>CSVList.csv</Filename>

<DocData format="base64">UkVGLSDQo=</DocData>

</Document>

</DocumentSet>

<MessageId>CABRECHICHARLT11/6/2008 3:45:57 PM</MessageId>

</FaxOptions>

</JobOptions>

<DocRef>CSVList1</DocRef>

</Table>

</Destinations>

<Part>

<DocRef>PDFDoc1</DocRef>

</Part>

</Contents>

</Message>

</JobSubmitRequest>

</soap:Body>

</soap:Envelope>

When the XML above is submitted to the system it will be processed and a Job will be setup once the Job has been setup a response will be returned that looks like the following:

<?xml version="1.0" encoding="UTF-8"?>

<SenderKey>http://test2api.pgiconnect.com/JobSubmit</SenderKey>

</Response>

</Header>

<Body>

</Status>

<MessageId>CABRECHICHARLT11/6/2008 3:45:57 PM</MessageId>

</Status>

<JobId>

</JobId>

</MessageResult>

</JobSubmitResult>

</Body>

</Envelope>

NOTE: the response is the JobSubmitResult which contains the JobId.

Asynchronous Mode

In asynchronous mode, there are two stages to every transaction. The first stage is a request/response pair initiated by the EasyLink Messaging API Client, in which the response will contain little more than an acknowledgement that the request has been received - the Body of the SOAP response will in fact be empty. The second stage is a request/response pair initiated by the EasyLink Messaging system, in which the request actually contains the results from processing the first request, and the response simply acknowledges receipt. The main point to note is that in order to take advantage of the asynchronous mode, the Client must provide a web service to which the Service will deliver the results.

For example, the client sends an async request to submit a job. This request includes a Request element in its SOAP Header that contains a SenderKey element. The value of the SenderKey (<SenderKey>http://www.bdrsoftware.com/Service1.asmx</SenderKey> ) element is the URL of the web service to which the EasyLink Messaging system will eventually send the results. Below is a sample Asynchronous Mode JobSubmit Request (please note this request has been manually altered for formatting purposes and the encoded documents have been truncated; to find working XML please search the site for XML Sample)

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<soap:Header>

<SenderKey>http://www.bdrsoftware.com/Service1.asmx</SenderKey>

<ReceiverKey>http://test2api.pgiconnect.com/soap/async</ReceiverKey>

<RequesterID>REQUESTER</RequesterID>

<Password>PASSWORD</Password>

</XDDSAuth>

</Authentication>

</Request>

</soap:Header>

<soap:Body>

<DocData format="base64">JVNCg==</DocData>

</Document>

<Filename>CSVList.csv</Filename>

</Document>

</DocumentSet>

<MessageId>CABRECHICHARLT11/3/2008 3:16:46 PM</MessageId>

</FaxOptions>

</JobOptions>

<DocRef>CSVList1</DocRef>

</Table>

</Destinations>

<Part>

<DocRef>PDFDoc1</DocRef>

</Part>

</Contents>

</Message>

</JobSubmitRequest>

</soap:Body>

</soap:Envelope>

This is the same request as a Sync Request with 2 exceptions. Once it needs to be submitted to the ASYNC URL and it needs to contain a <SenderKey>. Upon receiving this request, the EasyLink Messaging system puts it on a queue to be processed, and then immediately sends a SOAP reply to the client in the HTTP response, without waiting for the actual processing to be done. This reply will have an empty Body, but the SOAP Header will contain a Response element with a ProcessingId – this indicates that the message has been received and contains enough information for the client to correlate it with the request. Below is the initial response to the JobSubmit Request above.

<?xml version="1.0" encoding="UTF-8"?>

<ns1:Response>

<ns1:SenderKey>http://test2api.pgiconnect.com/async</ns1:SenderKey>

<ns1:ReceiverKey>http://www.bdrsoftware.com/Service1.asmx</ns1:ReceiverKey>

<ns1:ProcessingID>89EC019C-1800-081103231553614</ns1:ProcessingID>

</ns1:Response>

</Header>

<Body/>

</Envelope>

Later, when the task required by the initial request has been completed, in this case when the job has been submitted to the EasyLink Messaging service for delivery, the system will assemble a SOAP request and will make a call to the URL that was provided in the SenderKey of the original request (in this case http://www.bdrsoftware.com/Service1.asmx). This SOAP request will contain the Response Header element, and the Body will contain the result of the system processing. In this case the job id is included:

<?xml version="1.0" encoding="UTF-8"?>

<SenderKey>http://test2api.pgiconnect.com/soap/async</SenderKey>

<ReceiverKey>http://www.bdrsoftware.com/Service1.asmx</ReceiverKey>

</Response>

</Header>

<Body>

</Status>

<MessageId>CABRECHICHARLT11/3/2008 3:16:46 PM</MessageId>

</Status>

<JobId>

</JobId>

</MessageResult>

</JobSubmitResult>

</Body>

</Envelope>

NOTE: this does not mean that the job is completed; just that the job has been setup and has been queued for delivery. One of the common misconceptions is that the response to the web service means that the job has been completed and the response will contain the results of the job. This is NOT the case: the response to the web service is the response to the function call. So a JobSubmit will receive a JobSubmit Response and a JobSummary will receive a JobSummary Response.

Pros and Cons

ASYNC

PRO: Quick response from our system because the system just acknowledges that we received the data. However if something is missing in the data the error message gets sent back to the receiver. (So the initial ACK is just that an acknowledgement that we received data not verification that the data is correct)

PRO: Useful if you are sending or receiving LARGE amounts of data. (either large documents, over 25M)

CON: More complicated to setup a receiver

CON: Our system simply sends the response to the receiver once. If the response is lost for any reason or fails to send our system doesn’t retry.

SYNC

PRO: easy to implement no need to host a receiver

PRO: Response to a SYNC call tells you if there is an error or provides the data.

CON: could timeout when sending or receiving large amount of data

CON: when the SYNC call is submitted the calling program waits for the response. In most cases this response is returned in a few seconds.