X

Best Practices from Oracle Development's A‑Team

Retrieve and Update Task Payload with PCS REST API

Derek Kam
Consulting Solutions Architect

 

This blog has been retired

PCS has a number of REST APIs you can use to search for the tasks assign to a user/group, and retrieve the payload of a specific task as well as update the payload.  In PCS 16.3.5, a new Oracle form technology was introduced, hence, there are some changes to the REST API.

Prior to PCS 16.3.5, Frevvo WebForms was the main form technology used in PCS, when you use the PCS REST API to retrieve the payload of a specific task, it will always return an XML formatted payload.  With the introduction of the new PCS 16.3.5, if you are using the Oracle New Webforms, you have an option to specify whether you want the payload to be returned as JSON format or XML.

Use Case:  You want to retrieve a list of tasks that were assigned to a user or a group, and update the payload of a specific task.

To implement this use case, you need to use the following PCS REST API:

1. Retrieve a list of tasks

To retrieve a list of tasks that were assigned to a user or a group, you need to use the HTTP GET method on the /tasks REST endpoint e.g. https://example.com/bpm/api/3.0/tasks. The content type and accept header parameter must be set to “application/json”.

The tasks API supports several optional query parameters that make searching for tasks easier.  To find the specific task that you want to update, you can use the combination of keyword and assignment parameters.  Using keyword parameter allows you to search for a task using the task title, so when you are designing your Human Task, you will need to provide meaningful and searchable title that can be used for searching, for example “Loan Application Approval for #120-002-00”.  Below are some of the useful parameters that can be used for searching:

priority - Task priority from 1 (highest) to 5 (lowest) or Any (default)

dueDateFrom - Start of due date range in the format yyyy-mm-dd hh:mm:ss

dueDateTo - End of due date range in the format yyyy-mm-dd hh:mm:ss

assignment - Task assignees - MY, GROUP, MY_AND_GROUP (default), MY_AND_GROUP_ALL, REPORTEES, OWNER, REVIEWER, PREVIOUS, ALL, ADMIN

Keyword - Keyword in task title.

UpdateTaskPayload_1

2. Fetch Task Payload

From the response of the fetch list of tasks REST API, locate the TaskId and the URL of the task that you are interested in. This would be present in the first “items []” array or the number field in the array.  Once you have the task id, you can now use the HTTP GET method on this URL: http://example.com/bpm/api/3.0/tasks/{taskID}/payload to fetch the payload value associated with that task. The content type parameter must be set to “application/json”.

In some integration systems, you will need to set the accept header explicitly for a specific media type for the response.  In Oracle Service Bus (OSB), the outbound request header can be set using the transport header action.

UpdateTaskPayload_2

For example, if you want the response to be XML representation, you will need to set the Accept header value to “*” or “*/*” to indicate all media types.

UpdateTaskPayload_3

If you want the response to be a JSON representation, you will need to set the Accept header to “application/json”

UpdateTaskPayload_4

For Basic Forms (Frevvo Webforms) the response to the get Payload call is always an XML representation of the Payload.

For Oracle New WebForms, the response will be in JSON format if you set the Accept header setting to “application/json”.

UpdateTaskPayload_5

However, if the webform is associated with the Frevvo webform, and you have added the Accept header setting with application/json value, the response will be a 404 error.

UpdateTaskPayload_6

If you require the response to be in XML for New WebForms, make sure you remove the Accept: application/json header setting.

UpdateTaskPayload_7

 

3. Update Payload of the task

Basic Forms (Frevvo Webforms)

After you have retrieved the payload for a specific task, you can update the payload and send the update back to PCS to update the payload of a given task.  You can also use the same URL (e.g. http://example.com/bpm/api/3.0/tasks/{taskID}/payload ) as the fetch task payload but you will need to use the HTTP POST method.

For Basic forms, the task update REST API requires an xml payload as part of the POST request, the xml payload will be wrapped in the JSON request. You will also need to set the content-type to “application/json”.

Note: Each “(double quote) has been escaped by a \ (backslash). Another alternative is to use single quotes instead of double quotes. Also ensure that there are no newline characters with the payload.

For example:  Updating Task Payload associated with Basic Form

{

"xmlPayload":"<payload xmlns=\"http://xmlns.oracle.com/bpel/workflow/task\"><Address xsi:type=\"def:Address\" xmlns:ns1=\"http://xmlns.oracle.com/bpm/forms/schemas/Address\" xmlns:def=\"http://xmlns.oracle.com/bpm/forms/schemas/Address\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"><ns1:addressType>Street</ns1:addressType><ns1:city>SYD</ns1:city><ns1:country>Australia</ns1:country><ns1:currentAddress>true</ns1:currentAddress>     <ns1:endDate>2016-08-24</ns1:endDate><ns1:floorNumber/><ns1:housingSituation>Own</ns1:housingSituation><ns1:months>1</ns1:months><ns1:postCode>2001</ns1:postCode><ns1:startDate>2005-08-03</ns1:startDate><ns1:state>New South Wales</ns1:state><ns1:streetName>David</ns1:streetName><ns1:streetNumber>100</ns1:streetNumber><ns1:streetType>option1</ns1:streetType><ns1:unitNumber/><ns1:years>10</ns1:years></Address></payload>"

}

UpdateTaskPayload_8

New WebForms

If the task is associated with New WebForms, you can update the payload by using the JSON payload or the XML payload

For example:  Updating Task Payload using JSON Payload

UpdateTaskPayload_9

For example:  Updating Task Payload using XML Payload

UpdateTaskPayload_10

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha

Recent Content