APIs, SDKs, and Services > Embedding Request Forms in Standalone Web Pages > XML Binding
  

XML Binding

Processes deployed to the Process Server are available as simple XML bindings in addition to the standard SOAP binding providing that the process and deployment is WS-I compliant:

Invoking a Process

To invoke a process using a XML binding endpoint, you need to:
  1. 1. Set the POST header content-type header to text/xml
  2. 2. Set the POST payload (body content) to be the request xml element
  3. 3. Include authorization headers if needed
  4. 4. Send an HTTP POST message to the service XML endpoint
The response from the POST will be an HTTP 200/OK response with a content-type of text/xml. The response body will contain the service's response XML. The following snippet shows the HTTP request used to invoke the Loan Approval process using the humantaskProcessDemoService service.

POST /active-bpel/services/XML/humantaskProcessDemoService HTTP/1.1
Content-Length: 710
Content-Type: text/xml; charset=UTF-8
Authorization: Basic YWVhZG1pbjphZWFkbWlu
Host: localhost:8080
<loan:loanProcessRequest xmlns:loan=
"http://schemas.active-endpoints.com/sample/LoanRequest/2008/02/loanRequest.xsd">
<loan:loanType>Automobile</loan:loanType>
<loan:firstName>John</loan:firstNam>
<loan:lastName>Smith</loan:lastName>
<loan:dayPhone>2039299400</loan:dayPhone>
<loan:nightPhone>2035551212</loan:nightPhone>
<loan:socialSecurityNumber>123-45-6789</loan:socialSecurityNumber>
<loan:amountRequested>15000</loan:amountRequested>
<loan:loanDescription>Application to finance the purchase of a Toyota Prius</loan:loanDescription>
<loan:otherInfo>Down payment is US$7500</loan:otherInfo>
<loan:responseEmail>john.smith@example.com</loan:responseEmail>
</loan:loanProcessRequest>
The response looks like:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: text/xml;charset=utf-8
Transfer-Encoding: chunked
Date: Wed, 10 Mar 2010 22:53:40 GMT
<loan:status xmlns:loan="http://www.active-endpoints.com/wsdl/humantaskdemo">
Thank you for applying for the Automobile loan for the amount of US$15000.
Your loan is currently pending approval. You will receive an email once a decision has
been made.
</loan:status>
Fault Response
A fault is indicated with an HTTP response code of 500 and whose content-type is text/xml (instead of text/html or text/plain indicating a generic "internal server error"). An example of a fault response is shown here:

HTTP/1.1 500 Internal Server Error
Server: Apache-Coyote/1.1
Content-Type: text/xml;charset=utf-8
Transfer-Encoding: chunked
Date: Thu, 11 Mar 2010 19:09:51 GMT
Connection: close
<aex:Fault xmlns:aex="http://www.active-endpoints.com/2004/06/bpel/extensions/">
<faultcode name="systemError"
namespace="http://www.active-endpoints.com/2004/06/bpel/extensions/"/>
<faultstring>Could not find match for Operation from given parameters</faultstring>
</aex:Fault>
Attachments
When sending attachments the payload of the HTTP body must be multipart/related content, with the first part being the message XML payload (text/xml), followed by additional parts representing the attachments. Attachments sent with the payload are bound to the process variable associated with the message Receive activity.

POST /active-bpel/services/XML/humantaskProcessDemoService HTTP/1.1
Content-Type: multipart/related; type="text/xml"; start="<part1_id>"; boundary="the_boundry"
Content-Length: 1410
MIME-Version: 1.0
Host: localhost:8080
--the_boundry
Content-Type: text/xml; charset=UTF-8
Content-Transfer-Encoding: 8bit
Content-ID: <part1_id>
<loan:loanProcessRequest xmlns:loan=
"http://schemas.active-endpoints.com/sample/LoanRequest/2008/02/loanRequest.xsd">
<loan:loanType>Automobile</loan:loanType>
<loan:firstName>John</loan:firstName>
<loan:lastName>Smith</loan:lastName>
<loan:dayPhone>2039299400</loan:dayPhone>
<loan:nightPhone>2035551212</loan:nightPhone>
<loan:socialSecurityNumber>123-45-6789</loan:socialSecurityNumber>
<loan:amountRequested>15000</loan:amountRequested>
<loan:loanDescription>Application to finance the purchase of a Toyota Prius</loan:loanDescription>
<loan:otherInfo>Down payment is US$7500</loan:otherInfo>
<loan:responseEmail>john.smith@example.com</loan:responseEmail>
</loan:loanProcessRequest>
--the_boundry
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Content-ID: <part2_id>
[...Text Attachment Content...]
--the_boundry
Content-Type: image/jpeg
Content-ID: <part3_id>
Content-Transfer-Encoding: BASE64
Content-Description: Picture A
[...Image Content...]
--the_boundry--
For testing, you can use any HTTP client testing tool available to you. For example, SOAP-UI, cURL (a popular command line tool: http://curl.haxx.se/) and RESTClient (see http://code.google.com/p/rest-client/), a Java based application to test RESTful web services.

Using the RESTClient Tool

RESTClient is a Java application used to test RESTful services. It can be used to test a variety of HTTP communications including invoking Process Server processes using the XML binding endpoint. To use the GUI version of this tool, download the jar restclient-ui-2.3-jar-with-dependencies.jar library from http://code.google.com/p/rest-client/downloads/list.
To launch the application, run the command java -jar restclient-ui-2.3-jar-with-dependencies.jar. This will bring up the GUI application similar to the screenshot shown below.
  1. 1. To invoke the sample process in provided with this SDK, ensure that your server is running and that you have deployed the humantaskProcessDemo bpr provided with this SDK to it.
  2. 2. To send a XML POST message to invoke a service, set the service URL for the XML binding. For example, http://localhost:8080/active-bpel/services/XML/humantaskProcessDemoService.
  3. 3. In the Method tab, set the HTTP Method to POST.
  4. 4. In the Body tab, set content-type to text/xml.
  5. 5. In the Body tab, provide the xml request element. You can copy the <loan:loanProcessRequest> sample shown in the previous section.
  6. 6. Set authorization information if needed via Auth tab.
  7. 7. Press the Go button to send the request
  8. 8. The response from the service is then shown in the Body tab in the HTTP Response area.

Java Example

The following snippet shows one approach to sending an HTTP POST to a service endpoint. The complete code is available in the com.activevos.examples.xmlbinding.SimpleXmlServiceRequest class provided to you in the examples folder.
public class SimpleXmlServiceRequest {
/**
* Class to hold service response data.
*/
static class ServiceResponse {
static final int SUCCESS = 0;
static final int FAULTED = 1;
static final int ERROR = 2;
/** Code indicating if the service invoke was a success, fault or other error.*/
int responseCode;
/** Response xml data */
String responseData;
}

/**
* Invokes XML service using POST method returns service response.
*/
public static ServiceResponse invokeService(URL aXmlServiceUrl, String aXmlPayload,
String aUsername, String aPassword) throws IOException {
HttpURLConnection httpConnection = null;
BufferedReader reader = null;
OutputStreamWriter writer = null;
try
{
// create connection
URLConnection c = aXmlServiceUrl.openConnection();
httpConnection = (HttpURLConnection)c;
httpConnection.setRequestProperty("Content-Type", "text/xml");
httpConnection.setRequestProperty("Content-Length", Integer.toString(aXmlPayload.length()));
// Set credentials (if secured using BASIC auth).
if (aUsername != null && aPassword != null) {
// code to set the authorization header (e.g. BASIC)
}
httpConnection.setDoOutput(true);
httpConnection.setInstanceFollowRedirects(true);
// send the payload
writer = new OutputStreamWriter(httpConnection.getOutputStream());
writer.write(aXmlPayload);
writer.flush();
// read response
if ( httpConnection.getResponseCode() == HttpURLConnection.HTTP_OK
|| httpConnection.getResponseCode() == HttpURLConnection.HTTP_ACCEPTED ) {
reader = new BufferedReader(new InputStreamReader(httpConnection.getInputStream()));
} else {
reader = new BufferedReader(new InputStreamReader(httpConnection.getErrorStream()));
}
// read response
StringBuilder sb = new StringBuilder();
String line = null;
while ((line = reader.readLine()) != null) {
sb.append(line);
}

ServiceResponse response = new ServiceResponse();
response.responseData = sb.toString();
if ( httpConnection.getResponseCode() == HttpURLConnection.HTTP_OK
|| httpConnection.getResponseCode() == HttpURLConnection.HTTP_ACCEPTED ) {
// Success!
response.responseCode = ServiceResponse.SUCCESS;
} else if (httpConnection.getResponseCode() == HttpURLConnection.HTTP_INTERNAL_ERROR
&& httpConnection.getContentType().toLowerCase().startsWith("text/xml") ) {
// Faulted! (response code is 500 and content-type is text/xml
response.responseCode = ServiceResponse.FAULTED;
} else {
// http/transport or other error
response.responseCode = ServiceResponse.ERROR;
}
return response;
}
finally {
//
// clean up code goes here. E.g.: close writer, reader and disconnect http connection.
}
}
public static void main(String[] args) {
// Create sample request. In this example, the sample request is created using
// a string. Ideally, the XML element should be built using DOM i.e. with DocumentBuilderFactory,
// and DocumentBuilder.
String xmlRequest = "<loan:loanProcessRequest
xmlns:loan=\"http://schemas.active-endpoints.com/sample/LoanRequest/2008/02/loanRequest.xsd\">\n"
+ " <loan:loanType>Automobile</loan:loanType>\n"
+ " <loan:firstName>John</loan:firstName>\n"
+ " <loan:lastName>Smith</loan:lastName>\n"
+ " <loan:dayPhone>2039299400</loan:dayPhone>\n"
+ " <loan:nightPhone>2035551212</loan:nightPhone>\n"
+ " <loan:socialSecurityNumber>123-45-6789</loan:socialSecurityNumber>\n"
+ " <loan:amountRequested>15000</loan:amountRequested>\n"
+ " <loan:loanDescription>Application to finance the purchase of a Toyota Prius</loan:loanDescription>\n"
+ " <loan:otherInfo>Down payment is US$7500</loan:otherInfo>\n"
+ " <loan:responseEmail>john.smith@example.com</loan:responseEmail>\n"
+ "</loan:loanProcessRequest>";

try {
URL loanRequestUrl = new URL(
"http://localhost:8080/active-bpel/services/XML/humantaskProcessDemoService");
System.out.println("Invoking service...");
ServiceResponse response = invokeService(loanRequestUrl, xmlRequest, "username", "password");

if ( response.responseCode == ServiceResponse.SUCCESS ) {
System.out.println("Success:");
} else if ( response.responseCode == ServiceResponse.FAULTED ) {
System.out.println("Faulted:");
} else {
System.out.println("Error:");
}
System.out.println(response.responseData);
} catch (Exception e) {
e.printStackTrace();
}
}
}