|
 |
This article describes how a SOAP-with-Attachments package should be build in order to get it to eCircle. 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)
Using SOAP with Attachments
and Mime Packaging is certainly a bit more complicated that calling a simple SOAP method. But unlike such a simple method, this mechanism allows to transfer more data and several data pieces (files) at once. SOAP with Attachments uses the MIME Standard, to pack and encode several files into one package.
Resquest Structure#
HTTP-Headers
HTTP Body {
Mime Package {
first Mime Part (aka Main Part) {
SOAP Envelope {
SOAP Header
SOAP Body {
GroupControlXML
}
}
}
attachment mime Parts
(one or more)
}
}
Sample Transfer#
This is a sample protocol of a transfer to eC-MEssenger (not including the HTTP Protocol headers). It has only inlined data and as such does not make up a MIME Multipart package.HTTP Header (sample):
POST /eCMessageService/ HTTP/1.1 SOAPAction: http://webservices.ecircle-ag.com/eC-Messenge-Service Accept-Language: en-gb User-Agent: ...(set by your utility code, not required) Host: ...(your domain name, needed to route the request on HTTP level) Content-Length: 8226 Content-Type: multipart/related; boundary=rw1WAv0lX7frvgprJ8EC6fVyBDu_5hiILNl8x3V
(first) SOAP Part:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Header>
<authenticate xmlns="http://webservices.ecircle-ag.com/ws">
<realm>sysname</realm>
<email>user@email.domain</email>
<password>ecm-pass</password>
</authenticate>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<postGroupRequest xmlns="http://webservices.ecircle-ag.com/ws">
<control xmlns="http://webservices.ecircle-ag.com/ecm" group-id="700003764">
<group-definition>
<name>testgroup</name>
<isocountry>DE</isocountry>
<isolanguage>de</isolanguage>
<email-channel>
<email>test3@asptest1.ecircle-solutions.com</email>
</email-channel>
</group-definition>
<member-list add-mode="add" sync-mode="add">
<user>
<email>some@mail.domain</email>
<firstname>Some</firstname>
<lastname>Recipient</lastname>
</user>
</member-list>
<message message-id="new">
<send-date><immediately/></send-date>
<content>
<subject>subject</subject>
<text>message text</text>
<html>message html</html>
</content>
</message>
<delete-date><in>PT5M</in></delete-date>
</control>
</postGroupRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
The <SOAP-ENV:Envelope.. element starts the SOAP specified part. <postGroupRequest... finally introduces the first eCircle defined element (defined here) and <control... is the actual payload described in AsynchronousAPI.
You can identify the Mime packaging of the different parts by the -boundary- separators.
This would lead into a response as follows:
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<response xmlns="">
Control message is submitted for processing.
</response>
</soapenv:Body>
</soapenv:Envelope>
Here an example, that illustrates a HTTP POST with a mime encoded attachment:
POST http://192.168.99.212:8080/msgservice HTTP/1.1
Accept: text/xml, text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
SOAPAction:
Content-Type: multipart/related; type="text/xml"; boundary="----=_Part_0_20732290.1221489869756"
Cache-Control: no-cache
Pragma: no-cache
User-Agent: Java/1.6.0_07
Host: 192.168.99.212:8080
Proxy-Connection: keep-alive
Content-Length: 1607
------=_Part_0_20732290.1221489869756
Content-Type: text/xml; charset=utf-8
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Header>
<authenticate xmlns="http://webservices.ecircle-ag.com/ws"><realm>postgres-pages-xy</realm>
<email>tester@dev.muc.ecircle.de</email><password>xxxxxx</password></authenticate>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<postGroupRequest xmlns="http://webservices.ecircle-ag.com/ws">
<control xmlns="http://webservices.ecircle-ag.com/ecm" group-id="new" request-id="1234">
<group-definition>
<name>soap-test</name><isocountry>DE</isocountry><isolanguage>de</isolanguage>
<email-channel><email>test2@postgres-pages-xy.in</email></email-channel>
</group-definition>
<member-list add-mode="add" sync-mode="add">
<uri-reference>cid:recipients.xml.gz</uri-reference>
</member-list>
<message message-id="new">
<send-date><immediately/></send-date>
<content>
<subject>subject 2</subject>
<text>message text</text>
<html>message html</html>
</content>
</message>
<delete-date><in>PT5M</in></delete-date>
</control>
</postGroupRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
------=_Part_0_20732290.1221489869756
Content-Type: application/octet-stream
Content-Id: recipients.xml.gz
<ENCODED DATA>
------=_Part_0_20732290.1221489869756--
Note that the attachment is assumed to be compressed by default.
Authentication#
 |
Mime packaging#
Packing parts together is well defined in the related RFC's. You should use existing utilities in your preferred programming environment as building a syntactically valid package may be a error-prone process.
The article GroupJobPackage has more details. Here is more on Adressing the different parts in a SOAP Mime package.
Java Examples#
In Ressources you can find a Ressources/soap-client.zip
, that contains SOAP clients programmed in Java. This code illustrated several ways to compose and send a message using standard java components. There is also a example of a SSL secured transfer (More on SSL).