APIs, SDKs, and Services > Embedding Request Forms in Standalone Web Pages > Invoking a Process Using JSON

Invoking a Process Using JSON

Invoking a process using JSON is similar to the method described for the XML binding endpoint:

1. Prepare to send an HTTP POST message to the service JSON endpoint at http://host:port/active-bpel/services/JSON/serviceName.
2. Set the POST header content-type to application/json.
3. Set POST payload (body content) to be the string version of the JSON request.
4. Include authorization headers if needed.
5. Send an HTTP POST message to the service JSON endpoint.

The response from the POST is a HTTP 200/OK response with content-type of application/json. The response body will contain a JSON service response (as a string). The following snippet shows the HTTP request used to invoke the Loan Approval process using the humantaskProcessDemoService service. .

POST /active-bpel/services/JSON/humantaskProcessDemoService HTTP/1.1
Content-Length: 581
Content-Type: application/json; charset=UTF-8
Authorization: Basic YWVhZG1pbjphZWFkbWlu
Host: localhost:8080
{"loanProcessRequest":
{"xmlns":"http:\/\/schemas.active-endpoints.com\/sample\/LoanRequest\/2008\/02\/loanRequest.xsd",
"loanType":{"$t":"Automobile"},
"firstName":{"$t":"John"},
"lastName":{"$t":"Smith"},
"dayPhone":{"$t":"2039299400"},
"nightPhone":{"$t":"2035551212"},
"socialSecurityNumber":{"$t":"123-45-6789"},
"amountRequested":{"$t":"15000"},
"loanDescription":{"$t":"Application to finance the purchase of a Toyota Prius"},
"otherInfo":{"$t":"Down payment is US$7500"},
"responseEmail":{"$t":"john.smith@example.com"}
}
}

The response to the above request looks like:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{"status":
{"xmlns":"http:\/\/www.active-endpoints.com\/wsdl\/humantaskdemo",
"$t":"Thank you for applying for the Automobile loan for the amount of US$15000. Your loan is currently pending approval."
}
}

Faults

A fault response is returned with HTTP error code 500 and content-type application/json:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=utf-8
{"Fault":
{"xmlns":"http:\/\/www.active-endpoints.com\/2004\/06\/bpel\/extensions\/",
"faultcode":
{"name":"invalidVariables",
"namespace": "http:\/\/docs.oasis-open.org\/wsbpel\/2.0\/process\/executable",
"xmlns":""
},
"faultstring":
{"xmlns":"",
"$t":" fault error message"
}
}
}

Attachments

Similar to XML process invokes, the payload of the HTTP body must be multipart/related content, with the first part being the JSON payload with content-type application/json, followed by additional parts representing the attachments.

POST /active-bpel/services/JSON/humantaskProcessDemoService HTTP/1.1
Content-Type: multipart/related; type="application/json"; start="<part1_id>"; boundary="the_boundary"
Content-Length: 1234
MIME-Version: 1.0
Host: localhost:8080
--the_boundary
Content-Type: application/json; charset=UTF-8
Content-Transfer-Encoding: 8bit
Content-ID: <part1_id>
{"loanProcessRequest":
{"xmlns":"http:\/\/schemas.active-endpoints.com\/sample\/LoanRequest\/2008\/02\/loanRequest.xsd",
"loanType":{"$t":"Automobile"},
"firstName":{"$t":"John"},
"lastName":{"$t":"Smith"},
"dayPhone":{"$t":"2039299400"},
"nightPhone":{"$t":"2035551212"},
"socialSecurityNumber":{"$t":"123-45-6789"},
"amountRequested":{"$t":"15000"},
"loanDescription":{"$t":"Application to finance the purchase of a Toyota Prius"},
"otherInfo":{"$t":"Down payment is US$7500"},
"responseEmail":{"$t":"john.smith@example.com"}
}
}
--the_boundary
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Content-ID: <part2_id>
[...Text Attachment Content...]
--the_boundary
Content-Type: image/jpeg
Content-ID: <part3_id>
Content-Transfer-Encoding: BASE64
Content-Description: Picture A
[...Image Content...]
--the_boundary--

Attachments Using Multipart Form-Data

Processes can be invoked using a multipart/form-data type payload (normally used by HTML forms). When using this content-type, Process Server requires the form-data to contain one field with name _json. The value of this field must contain the JSON request.

POST /active-bpel/services/JSON/humantaskProcessDemoService HTTP/1.1
Content-Type: multipart/form-data; boundary="the_boundary"
Content-Length: 3449
MIME-Version: 1.0
Host: localhost:8080
--the_boundary
Content-Disposition: form-data; name="_json"
{"loanProcessRequest":{"xmlns":"http:\/\/schemas.active-endpoints.com\/sample\/LoanRequest\/2008\/02\/loanRequest.xsd","loanType":{"$t":"Automobile"},"firstName":{"$t":"John"},"lastName":{"$t":"Smith"},"dayPhone":{"$t":"2039299400"},"nightPhone":{"$t":"2035551212"},"socialSecurityNumber":{"$t":"123-45-6789"},"amountRequested":{"$t":"15000"},"loanDescription":{"$t":"Application to finance the purchase of a Toyota Prius"},"otherInfo":{"$t":"Down payment is US$7500"},"responseEmail":{"$t":"john.smith@example.com"}}}
--the_boundary
Content-Disposition: form-data; name="file_1"; filename="picture.gif"
Content-Type: image/gif
[image content]
--the_boundary--

The above request was generated by the HTML form:

Normally the multipart/form-data request generation and handling of the response is done using JavaScript (for AJAX-style browser applications). Note that the response to a process invoke (with or without attachments) using multipart/form-data, is an application/json response (as shown in previous examples--use the table of contents to see them). Since a response from a process can have attachments in addition to the response message (JSON), you can limit the response to the message (JSON) only by specifying messageOnly=true in the query string. Similarly, to restrict the response to contain only the attachments (if the process sends back attachments), use attachmentOnly=true in the query string.

ActiveVOS XML and JSON Bindings for Services

Some AJAX-based form submit scripts that support file upload expect the return content-type to be text/html (instead of application/json) because of the way scripts target iFrames. In these cases, you specify parameter responseContentType=text/html. If the responseContentType IS present, Process Server uses the value defined by the parameter as the response content-type instead of the default application/json.

A few AJAX file upload scripts such as the jQuery Forms Plugin (see http://plugins.jquery.com/project/form/) also require responses to multipart/form-data forms POSTs to be wrapped in a HTML element such as the textarea tag. Do this by using the responseWrap parameter. The value of this parameter should be the HTML element tag name.

The following shows HTML file upload form used by the jQuery Forms plugins, which requires the response to be returned wrapped in a HTML textarea tag with content-type head of text/html:

RESTClient

You can use the RESTClient test application to send JSON data to the Process Server. The content-type of the payload should be set to application/json.

Invoking a Process with jQuery

The following example shows how to invoke a process using AJAX with jQuery. The scripts used for the request require jQuery 1.3.2+ (http://www.jquery.com) and json2.js (http://www.JSON.org/json2.js). The json2.js script is used to convert a JSON object to a string.

The AE_AJAX_SERVICE_UTIL Javascript object in the ae-avc-util.js script included with the SDK provides has a helper function postJSON(url, jsonRequest, successCallbackFn, faultCallbackFn, errorCallbackFn) to POST JSON data.

Here is another example that uses the WS-HumanTask (WSHT) API getMyTasks operation via JSON. This example fetches tasks using the API and populates a HTML table with the results.

<! -- html snippet -->
<table cellpadding="2" border="1">
<thead>
<tr><th colspan="5">Get My Tasks Response (from JSON):</th></tr>
<tr><th>Task ID</th> <th>Status</th><th>Owner</th>
<th>PresentationName</th><th>PresentationSubject</th></tr>
</thead>
<! -- the table body will be populated using JavaScript -->
<tbody id="taskList">
</tbody>
</table>

// getMyTasks reqests
var getMyTasksRequest = {
"getMyTasks" : {
"xmlns" : "http://www.example.org/WS-HT/api/xsd",
"taskType" : { "$t" : "TASKS" },
"genericHumanRole" : { "$t" : "POTENTIAL_OWNERS" },
"status" : { "$t" : "READY" },
"maxTasks" : { "$t" : "10" }
}
};
// send JSON
AE_AJAX_SERVICE_UTIL.postJSON(
// task-client service url
"http://localhost:8080/active-bpel/services/JSON/AeB4PTaskClient-taskOperations",
// req.
getMyTasksRequest,
// success callback of JSON data
function(aJsonResponse) {
// display results in a table
populateTaskList(aJsonResponse);
},
// fault callback of JSON data
function(aJsonFault) {
alert("Fault!");
},
// http error callback
function(aStatusCode, aStatusMessage) {
alert("Transport error: " + aStatusCode + " " + aStatusMessage);
}
);
//
// This function takes a getMyTasksResponse element (in JSON) and populates
// the tasks in an HTML table.
//
function populateTaskList(aJsonResponse) {
// Note: aJsonResponse contains getMyTasksResponse object)
// clear current contents by removing all children of the table (table rows)
$("#taskList").empty();
// check to make sure response exists.
if (!aJsonResponse.getMyTasksResponse) {
alert("Response 'getMyTasksResponse' expected.");
return;
}
// get list of task abstracts (//htdt:getMyTasksResponse/htdt:taskAbstract)
var taskAbstracts = AE_JSON_NODE_UTIL.getElements
(aJsonResponse.getMyTasksResponse.taskAbstract);
var i;
// for each taskAbstract, build the html row and append to table tbody.
for (i = 0; i < taskAbstracts.length; i++) {
var html = "<tr>";
html += "<td>" + AE_JSON_NODE_UTIL.getText(taskAbstracts[i].id, "n/a") + "</td>";
html += "<td>" + AE_JSON_NODE_UTIL.getText(taskAbstracts[i].status, "n/a") + "</td>";
html += "<td>" + AE_JSON_NODE_UTIL.getText(taskAbstracts[i].actualOwner, "n/a") + "</td>";
html += "<td>" + AE_JSON_NODE_UTIL.getText(taskAbstracts[i].presentationName, "n/a") + "</td>";
html += "<td>" + AE_JSON_NODE_UTIL.getText(taskAbstracts[i].presentationSubject, "n/a") + "</td>";
html += "</tr>";
// append to table
$("#taskList").append(html);
};
}

Using AE_AJAX_SERVICE_UTIL Functions

The AE_AJAX_SERVICE_UTIL Javascript object (in ae-avc-util.js) has the following utility functions related to making JSON invokes:

•getActiveVOSServiceURL
•postJSON

getActiveVOSServiceUrl(serviceNamePath)

A helper function that creates the endpoint URL to the given service name by appending the service name to a predefined engine endpoint. The engine URL should be assigned (at the start of your script) to the global variable AE_ACTIVEVOS_ENGINE_URL. If a value to AE_ACTIVEVOS_ENGINE_URL is not assigned, then http://localhost:8080/active-bpel is used.

If a value is assigned to the global variable AE_ACTIVEVOS_PROXY_URL, then this function returns the proxy URL with service URL in the query string in a parameter named destination. See example below.

// Define engine context URL and optional proxy URL at the start of your script.
// If the engine URL is not given, 'http://localhost:8080/active-bpel' is used.
// Note: AE_ACTIVEVOS_ENGINE_URL is global variable declared in ae-avc-util.js.
// You only need to assign it a value (to server /active-bpel context).
AE_ACTIVEVOS_ENGINE_URL = "http://demoserver:81/active-bpel";

// Optionally, if you are using a proxy for AJAX requests, you can
// assign it a value here:
// AE_ACTIVEVOS_PROXY_URL = "http://localhost:8080/proxy";
// for example, JSON service URL.
var loanServiceXmlUrl = AE_AJAX_SERVICE_UTIL.getActiveVOSServiceUrl("JSON/humantaskProcessDemoService");

// loanServiceXmlUrl is now equivalent to:
// AE_ACTIVEVOS_ENGINE_URL + "/services/" + "JSON/humantaskProcessDemoService"
// for example,
// http://demoserver:81/active-bpel/JSON/humantaskProcessDemoService
// If a value to AE_ACTIVEVOS_PROXY_URL is assigned, the 'loanServiceXmlUrl' becomes part of
// the proxy URL string parameter named 'destination'. For example,
// http://localhost:8080/proxy?destination=http://demoserver:81/active-bpel/JSON/humantaskProcessDemoService
// For example, XML service URL.
var loanServiceXmlUrl = AE_AJAX_SERVICE_UTIL.getActiveVOSServiceUrl("XML/humantaskProcessDemoService");

postJSON(aServiceUrl, aJsonData, aOnSuccessFn, aOnFaultFn, aOnErrorFn, aTimeOut)

Sends the JSON request to the server using HTTP POST and calls back with the JSON response. This function also handles error responses and callbacks either the JSON fault handler or the HTTP transport level error handler. Only the aServiceUrl and aJsonData are required.