APIs, SDKs, and Services > XML-JSON API > Accessing the WS-Human Task API Using JSON
  

Accessing the WS-Human Task API Using JSON

The following topics describe how to access the WS-HUMAN Task API using JSON

Constants for Common String Literals

Constants for Common String Literals
The AE_TASK_GLOBALS in ae-avc-tasks.js contains common constants that can be used from your code. For example, the string 'illegalArgument' (WSHT fault name) is defined in AE_TASK_GLOBALS.TASK_FAULT_NAMES.ILLEGAL_ARGUMENT. The http://www.example.org/WS-HT namespace is defined in AE_TASK_GLOBALS.NAMESPACES.XMLNS_HTD. Additional details are available in the AeTaskGlobals class in the ae-avc-tasks.js script.

Utility Functions

Utility Functions
The getMyTasks example provided in the Invoking a Process with jQuery section (the full example is located in json-getTasks.html) demonstrated how to send a WSHT getMyTasks request to the server using AE_AJAX_SERVICE_UTIL.postJSON() utility function. The ae-avc-tasks.js script contains the AE_TASK_UTIL instance with the following convenience functions:
AE_TASK_UTIL.getFaultData(aJsonFault)
Returns an object {faultName : "wshtFaultName", message : "faultMessageStr"} or null if the aJsonFault is not a WSHT SOAP fault. The 'wshtFaultName' values are standard WSDL: illegalArgument, illegalAccess, illegalOperation, and recipientNotAllowed.

// code that handles fault due to a human task operation invoke.
// check if this is a WSHT fault
var faultData = AE_TASK_UTIL.getFaultData(aJsonFault);
if (faultData != null) {
// wsht fault.
if (faultData.faultName == AE_TASK_GLOBALS.TASK_FAULT_NAMES.ILLEGAL_ARGUMENT) {
alert("illegal arg fault: " + faultData.message);
}
} else {
// system soap fault?
var soapFaultData = AE_AJAX_SERVICE_UTIL.getSystemFault(aJsonFault);
if (soapFaultData != null) {
alert("SOAP fault. Fault name:" + soapFaultData.name
+ ", message:" + soapFaultData.message);
}
}
AE_TASK_UTIL.isFault(aJsonResponse)
Returns true if the JSON object aJsonResponse is a known WSHT fault (per WSDL).
AE_TASK_UTIL.createGetTasksRequest(aParams, aGetTasksTemplate)
Creates a generic request getTasks request and returns the JSON object. The params object contains the optional values. The options are:
Provide a value of null to remove existing elements.
If the optional aGetTasksTemplate object, which is an existing JSON request, is given, aGetTasksTemplate is first cloned, and then the params are applied.
To create the following request:

<aeb:getTasks
xmlns:aeb="http://schemas.active-endpoints.com/b4p/wshumantask/2007/10/aeb4p-task-state-wsdl.xsd" >
<htdt:getMyTasks xmlns:htdt="http://www.example.org/WS-HT/api/xsd">
<htdt:taskType>TASKS</htdt:taskType>
<htdt:genericHumanRole>POTENTIAL_OWNERS</htdt:genericHumanRole>
<htdt:status>READY</htdt:status>
<htdt:status>RESERVED</htdt:status>
<htdt:maxTasks>5</htdt:maxTasks>
</htdt:getMyTasks>
<aeb:taskIndexOffset>0</aeb:taskIndexOffset>
</aeb:getTasks>
Normally, you will need to create the JSON object:

var getTasksRequest = {
"getTasks" : {
"xmlns" : "http://schemas.active-endpoints.com/b4p/wshumantask/2007/10/aeb4p-task-state-wsdl.xsd",
"getMyTasks" : {
"xmlns" : "http://www.example.org/WS-HT/api/xsd",
"taskType" : { "$t" : "TASKS" },
"genericHumanRole" : { "$t" : "POTENTIAL_OWNERS" },
"status" : [ {"$t" : "READY"} , {"$t" : "RESERVED"} ],
"maxTasks" : { "$t" : "5"}
},
"taskIndexOffset" : { "$t" : "0" }
}
}
With the AE_TASK_UTIL.createGetTasksRequest() function, the code to create the above request is:

var getTasksRequest = AE_TASK_UTIL.createGetTasksRequest( {
taskType : "TASKS",
genericHumanRole : "POTENTIAL_OWNERS",
status : ["READY", "RESERVED"],
maxTasks : 5,
taskIndexOffset : 0
});
// getTasksRequest contains JSON for <getTasks/> element used
// in getTasks operation for AE specific API extension at AEB4P-aeTaskOperations
// service.

// The WSHT getMyTasks request can be extracted in the following way:
var wshtGetMyTasksRequest = { "getMyTasks" : getTasksRequest.getTasks.getMyTasks };

WSHT API

The AeTaskApi class (in ae-avc-tasks.js script) can be used to access and operate on tasks. A few common functions are shown below. Refer to AeTaskApi in ae-avc-tasks.js for additional functions and details.
getTasks(aGetTasksRequest, aSuccessCallbackFn, aFaultCallbackFn, aErrorCallbackFn)
Invokes the getTasks operation for Informatica-specific API extension at AEB4P-aeTaskOperations service. On success, the response callback returns the JSON equivalent of the <htdt:getMyTasksResponse/> element.
// Assign the server URL to AE_ACTIVEVOS_ENGINE_URL global variable. This is where
// the service requests are sent. (note: AE_ACTIVEVOS_ENGINE_URL is global variable
// declared in ae-avc-util.js.)
AE_ACTIVEVOS_ENGINE_URL = "http://localhost:8080/active-bpel";

// create JSON request for getTasks operation. E.g. get upto 10 unclaimed tasks.
var getTasksRequest = AE_TASK_UTIL.createGetTasksRequest( {
taskType : AE_TASK_GLOBALS.GETMYTASKS_TASK_TYPE.TASKS, // same as string "TASKS"
// same as string "POTENTIAL_OWNERS"
genericHumanRole : AE_TASK_GLOBALS.GENERIC_HUMAN_ROLE.POTENTIAL_OWNERS,
status : AE_TASK_GLOBALS.TASK_STATUS.READY, // "READY"
maxTasks : 10
});

// Create AeTaskApi object and get the task list via getTasks() operation.
var taskApi = new AeTaskApi();
taskApi.getTasks(
getTasksRequest, // request JSON object

function(aJsonResponse) { // success callback of JSON data
// handle success response
alert("Success!");
// get list of task abstracts (//htdt:getMyTasksResponse/htdt:taskAbstract)
var jsonTaskAbstracts =
AE_JSON_NODE_UTIL.getElements(aJsonResponse.getTasksResponse.getMyTasksResponse.taskAbstract);
var i;
for (i = 0; i < jsonTaskAbstracts.length; i++) {
// wrap json data in AeTaskAbstract object for convenience accessors.
// (see ae-avc-tasks.js for AeTaskAbstract)

var taskAbstractObj = new AeTaskAbstract( jsonTaskAbstracts[i] );
alert( "Task id: " + taskAbstractObj.getId() );
alert( "Task name: " + taskAbstractObj.getName() );
alert( "Task status: " + taskAbstractObj.getStatus() );
}
},

function(aJsonFault) { // fault callback of JSON data
alert( "Fault!");
},

function(aStatusCode, aStatusMessage) { // http error callback
alert( "Transport error: " + aStatusCode + " " + aStatusMessage);
}
);
getInstance(aTaskId, aSuccessCallbackFn, aFaultCallbackFn, aErrorCallbackFn)
Invokes the Informatica-specific getInstance() operation on the extension service at AEB4P-aeTaskOperations service. On success, the callback is an AeTask object (see ae-avc-tasks.js).

// ...
// setup AE_ACTIVEVOS_ENGINE_URL, and the like
// ...
var taskApi = new AeTaskApi();
taskApi.getInstance(
"urn:b4p:1235", // task ID

function(aTask) { // handle success response
// aTask is an instance of AeTask (see ae-avc-tasks.js).
alert( "Got task, id=" + aTask.getId() );
alert( "Task name: " + aTask.getName() );
alert( "Task status: " + aTask.getStatus() );
// aTask.getJson() returns the underlying raw JSON data structer.
// aTask.getOwner() returns current owner.
var inputPartJson = aTask.getInput(); (// for input by partname, use aTask.getInput('nameOfPart');
},

function(aJsonFault) {
alert("Fault!");
},
function(aStatusCode, aStatusMessage) {
alert("Transport error: " + aStatusCode + " " + aStatusMessage);
}
);
invokeSimpleWshtRequest(aCommand, aTaskId, aSuccessCallbackFn, aFaultCallbackFn, aErrorCallbackFn)
Invokes a simple WSHT operation such as claim against the given task ID. The supported list of operation commands are defined in AE_TASK_GLOBALS.SIMPLE_WSHT_OPERATIONS constant.

var taskApi = new AeTaskApi();
var taskId = "urn:b4p:1234";
// claim
taskApi.invokeSimpleWshtRequest(
AE_TASK_GLOBALS.SIMPLE_WSHT_OPERATIONS.CLAIM,
taskId,
function(aClaimResponse) {
// success (json data)
},
function(aFaultResponse) {
// fault (json data)
},
function(aStatusCode, aStatusMessage) {
//error
}
);

// start
taskApi.invokeSimpleWshtRequest(
AE_TASK_GLOBALS.SIMPLE_WSHT_OPERATIONS.START,
taskId,
function(aStartResponse) {
// success (json data)
},
// ... fault and error handlers omitted for brevity ...
);

// complete
taskApi.invokeSimpleWshtRequest(
AE_TASK_GLOBALS.SIMPLE_WSHT_OPERATIONS.COMPLETE,
taskId,
function(aStartResponse) {
// success (json data)
},
// ... fault and error handlers omitted for brevity ...
);
setOutput(aTaskId, aPartName, aOutputPart, aSuccessCallbackFn, aFaultCallbackFn, aErrorCallbackFn)
Sets the task output data given the task ID, the output part name, and the output JSON data:

var taskApi = new AeTaskApi();
var taskId = "urn:b4p:1234";
// message part name per wsdl
var partName = "response";
// the <loan:loanApprovalResponse /> in JSON.
var outputJson =
{"loanApprovalResponse":
{
"xmlns":
"http:\/\/schemas.active-endpoints.com\/avoscentral\/LoanRequest\/2009\/07\/avc-loanapproval.xsd",
// other attributes and elements omitted for brevity.
}
};

// set output data
taskApi.setOutput(
taskId,
partName,
outputJson,
function(aSetOutputResponse) {
// success (json data)
},
function(aFaultResponse) {
// fault (json data)
},
function(aStatusCode, aStatusMessage) {
//error
}
);

Accessing AeTask

The AeTask class (in ae-avc-tasks.js script) is a wrapper for the <taskInstance /> element. This wrapper provides getters and setters for frequently used properties.
One way to get an instance of AeTask is by using the AeTaskApi.getInstance(...) function:

// ...
// setup AE_ACTIVEVOS_ENGINE_URL etc.
// ...
var taskApi = new AeTaskApi();
taskApi.getInstance(
"urn:b4p:1235", // task ID

function(aTask) { // handle success response
// aTask is an instance of AeTask (see ae-avc-tasks.js).
alert( "Got task, id: " + aTask.getId() );
alert( "Task name: " + aTask.getName() );
alert( "Task status: " + aTask.getStatus() );
// aTask.getJson() returns the underlying raw JSON data structer.
// aTask.getOwner() returns current owner.
},

function(aJsonFault) {
alert("Fault!");
},
function(aStatusCode, aStatusMessage) {
alert("Transport error: " + aStatusCode + " " + aStatusMessage);
}
);
Refer to AeTask in ae-avc-tasks.js for additional functions and details. Getters and Setters to task input/output data are described below:
Functions that you can use are:
getInputPart(aPartName)
Returns the task input part data given the part name (per WSDL message). If the aPartName is not given, the first available part is returned.

//
// Task is an instance of AeTask, obtained via AeTaskApi.getInstance(...)
// (assuming using the Loan Approval human task example)
//
// <message name="WshtLoanInput">
// <part name="request" element="loan:loanProcessRequest" />
// </message>
// <message name="WshtLoanOutput">
// <part name="response" element="loan:loanApprovalResponse" />
// </message>
var loanRequestInput = task.getInput("request"); // 'request' is the part name

// Note: task.getInput() returns first available part since part name is not given.
alert("Firt Name = " + loanRequestInput.loanProcessRequest.firstName);
alert("Loan Amount = " + loanRequestInput.loanProcessRequest.amountRequested);
getOutputPart(aPartName)
Returns the task out part data given the part name (per WSDL message). If the aPartName is not given, the first available part is returned. If part data is not available, null is returned.

var loanOutput = task.getOutput("response"); // 'response' is the output part name
// check for null in case output is not set.
if (loanOutput != null) {
alert("Approved? = " + loanOutput.loanApprovalResponse.responseToLoanRequest);
}
setOutputPart(aPartName, aPartData)
Sets the output part data in the AeTask instance (in-memory). This method does not 'save' (invokes WSHT setOutput on the server). To save, you must either use AeTask.saveOutputParts (preferred) or AeTaskApi.setOutput(...).

// First time use, create JSON output:
// var loanOutput = { {"loanApprovalResponse" : ... }};
// or getOutput() to access current value if the output has already been set.
var loanOutput = task.getOutput("response");

// modify data
AE_JSON_NODE_UTIL.setText(loanOutput.loanApprovalResponse.responseDescription, "Some Text");

// Set output (in-memory only)
task.setOutput("response", loanOutput);

// Now, save all available parts to the server using the AeTaskApi.
var taskApi = new AeTaskApi();
task.saveOutputParts(
taskApi,
function(aSetOutputResponse) {
// success (json data)
},
function(aFaultResponse) {
// fault (json data)
},
function(aStatusCode, aStatusMessage) {
//error
}
);

Task Attachment URL

Task Attachment URL
In some cases, you may want to display attachment information on a Web page. In order to do this, you need to access the list of attachment meta data (attachment infos) from the WSHT getAttachmentInfos operation or via the attachmentInfo elements that are part of taskInstance (obtained from the getInstance extension operation).
The URL to the attachment content can be built using the AE_TASK_UTIL.getAttachmentUrl(taskId, attachmentName, attachmentId) function.

//
// 1) Using getAttachmentInfos wsht API call.
//
var taskId = "urn:b4p:1235"; // task id
var getAttachmentInfosReq = {
"getAttachmentInfos" : {
"xmlns" : "http://www.example.org/WS-HT/api/xsd",
"identifier" : {
"$t" : taskId
}
}
};
AE_AJAX_SERVICE_UTIL.postJSON(
// task-client service url
"http://localhost:8080/active-bpel/services/JSON/AeB4PTaskClient-taskOperations",
// req.
getAttachmentInfosReq,
// success callback of JSON data
function(aJsonResponse) {
// handle getAttachmentInfosResponse
var attachmentInfoList = AE_JSON_NODE_UTIL.getElements(aJsonResponse.getAttachmentInfosResponse.info);
var i;
for (i = 0; i < attachmentInfoList; i++) {
var info = attachmentInfoList[i];
var attachmentId = AE_JSON_NODE_UTIL.getText(info.attachmentId);
var attachmentName = AE_JSON_NODE_UTIL.getText(info.name); // file name
var contentType = AE_JSON_NODE_UTIL.getText(info.contentType); // mime type.
var attachUrl = AE_TASK_UTIL.getAttachmentUrl(taskId, attachmentName, attachmentId);
// do something with this info such as displaying on page.
// (the attachUrl can be used for href attribute in <a> tags and src in <img> tags)
}
},
// fault callback of JSON data
function(aJsonFault) {
alert("Fault!");
},
// http error callback
function(aStatusCode, aStatusMessage) {
alert("Transport error: " + aStatusCode + " " + aStatusMessage);
}
);
//
// 2) Alternate method of getting attachment info via AeTask object.
//
var taskApi = new AeTaskApi();
taskApi.getInstance(
"urn:b4p:1235", // task ID

function(aTask) { // handle success response
var attachmentInfoList = aTask.getAttachments();
var i;
for (i = 0; i < attachmentInfoList; i++) {
var info = attachmentInfoList[i].attachmentInfo;
var attachmentId = AE_JSON_NODE_UTIL.getText(info.attachmentId);
var attachmentName = AE_JSON_NODE_UTIL.getText(info.name); // file name
var contentType = AE_JSON_NODE_UTIL.getText(info.contentType); // mime type.
var attachUrl = AE_TASK_UTIL.getAttachmentUrl(aTask.getId(), attachmentName, attachmentId);
// do something with this info such as displaying on page.
// (the attachUrl can be used for href attribute in <a> tags and src in <img> tags
}
},

function(aJsonFault) {
alert( "Fault!");
},
function(aStatusCode, aStatusMessage) {
alert( "Transport error: " + aStatusCode + " " + aStatusMessage);
}
);