|
 |
The asynchronous job interface uses comprehensive XML data sets that can be transferred to eCircle in various ways.
Together with that XML, other mass data like recipient lists, attachments or images may be transferred.
Unlike other API's, this API works within group context.
XML+binary data = A package#
This interface is called asynchronous, because you hand over a potentially big and complex job to be executed first, without "waiting" for the completion of this order by eCircle. Instead, you'll get a response sometime later, after a successful completion of all tasks (sometimes also upon partial results or failures).The data you need to transfer may be heavy too, for emails you may want to transfer huge address lists to us. The messages may contain images or attachments wich need to get to us first, before a message to the recipient is constructed. For this purpose, you may put your data, the XML as well as the binary data together into a package before you sent it to us.
This package may be a simple zip-File, or, more suitable for automation, a mime-Package that is transferred via the SOAP-with-Attachments mechanism.
See GroupJobPackage for a detailed discussion of the various XML parts and how they are related within each other in package.
There is a API Test-Page to manually exercize with the rather complex XML object. In eC-Messenger 5.2ff you can find this page, when setting up a SOAP-ControlMessage-Activity (Administration->Activity->Time Based-> New "SOAP Control"->"Test your Message") Note the in the authentication of such a async message, the eC-M' sysname is to be used, NOT the http access url (as it is in the synchronous SOAP interface)Transfering a package to eCircle#
- SOAP/w Attachments via HTTP
- Transfering binary information using the SOAP mechanisms is defined by the W3C
. Unlike the SynchronousSoapAPI, this procedure is a bit more complicated, as it requires to create Mime-Messages which contain the related parts. The package itself is finally transported using the well known HTTP protocol. See SoapWithAttachments for more details.
http://<your-domain-at-ecircle>/eC-MessageService. There is currently no WSDL available. There is some Java Sample Code
- FTP/SCP
- It is possible to package your data into a zip-File and sent it over to us. JobTransferWithFTP explaines this more.
- Web UI
- We offer a simple user interface in order to exersize the creation of a control XML file. You are free to use this interface also for simple HTTP transfers: just build a script that loads that various package parts to that page. In this case, a big part of the processing is done synchronous - as it is primarily intended for human testing. So the overall data may not be too big in this case. This UI can be found under the Administration->Triggers->ProcessExternalJob.
Processing a XML Job package#
 |
If accepting the package fails on our side, a protocol error may be given. For a SOAP transfer, a message is syntactically checked still while a connection to the sender is established. This is not the case for FTP transfers, where processing only starts after the whole package was transferred, so only FTP related errors may show up.
Further processing such a package leads to a controlResultMessage, that contains an attribute processing-result whichmay have the following states:
- COMPLETE
- All processing steps finished without any error indication. Such a result is sent to the address defined in the node success-report-address
- PARTIAL
- Processing passed the initial steps (see picture below), but some of the subsequent processing steps did have errors. Such a result is sent to the address defined in the failure-report-address node. More information can be obtained from the controlResultMessage's resultType-Nodes.
- FAILURE
- Processing failed in some early processing steps and was not continued. Such a result is sent to the failure-report-address.
A simple way for a caller to check the completion of the processing is to verify that the control-result message that is sent to the success-report-address- contains a processing-result=”COMPLETE” -Attribute in its top-Level Node .
It is possible to use the same addresses for both, success-report-address and failure-report-address. Up to 10 addresses may be scheduled for each node.
[#1] You'll have to HTTP POST your message to this location, in case you'll want to check this access point. A http GET (as done with your browser) will only lead to an AXIS Error. A POST will respond with a proper SOAP fault, similiar to this one..
<soapenv:Envelope>
<soapenv:Body>
<soapenv:Fault>
<faultcode>ns1:Client.NoSOAPAction</faultcode>
<faultstring>no SOAPAction header!</faultstring>
<detail>
<ns2:stackTrace>
no SOAPAction header!
at org.apache.axis.transport.http.AxisServlet.getSoapAction(...
...
See also EcircleDeveloper - GroupStatusXMLReport - InterfaceOptionsComparison - MessageStatusXMLReport - Ressources - SampleControlXML - SoapWithAttachments - XMLMessageType