Previous	Next		Contents	Index	Glossary

Attention: The Workflow Engine traps errors produced by function activities by setting a savepoint before each function activity. If an activity produces an unhandled exception, the engine performs a rollback to the savepoint, and sets the activity to the ERROR status. For this reason, just as with PL/SQL procedures, you should never commit within the Java procedure of a function activity. The Workflow Engine never issues a commit as it is the responsibility of the calling application to commit.

Many Workflow Engine and Notification APIs have corresponding Java methods that your Java program can call to communicate with Oracle Workflow. See: Oracle Workflow Java Interface.

To invoke a custom Java class from within a workflow process, create an external Java function activity that calls the class. See: To Create a Function Activity.

Java function activities are implemented as external procedures. When the Workflow Engine reaches an external Java function activity, the Workflow Engine places a message on the Workflow 'Outbound' queue. The Java Function Activity Agent monitors this queue and calls the class indicated in the Function Name property. When the Java procedure is complete, the Java Function Activity Agent enqueues the results onto the 'Inbound' queue. See: Setting Up the Java Function Activity Agent.

Note: These 'Outbound' and 'Inbound' queues are separate from the queues used for the Business Event System. In a future release, this function processing will be implemented within the Business Event System using a specialized queue handler to handle dequeue and enqueue operations. See: Workflow Queue APIs.

After a Java procedure completes, you must run a background engine to process the 'Inbound' queue and complete the function activity. Otherwise, the activity will remain in the DEFERRED status. See: Setting Up Background Engines.

You must include the JAR files containing your custom classes in your CLASSPATH to make the classes accessible to the Java Function Activity Agent. The custom class files should reside on the same platform where the Java Function Activity Agent is run. The Java Function Activity Agent does not need to reside on the same tier as the database, however.

The example in this section is numbered with the notation 1-> for easy referencing. The numbers and arrows themselves are not part of the procedure.

1->	package oracle.apps.fnd.wf;
2->	import java.io.*;
	import java.sql.*;
	import java.math.BigDecimal;
	import oracle.sql.*;
	import oracle.jdbc.driver.*;
	import oracle.apps.fnd.common.*;
	import oracle.apps.fnd.wf.engine.*;
	import oracle.apps.fnd.wf.*;
3->	public class className extends WFFunctionAPI {
4->	public boolean execute(WFContext pWCtx){
5->	ErrorStack es = pWCtx.getWFErrorStack();
	try
	{
6->	WFAttribute lAAttr = new WFAttribute();
	WFAttribute lIAttr = new WFAttribute();
7->	loadActivityAttributes(pWCtx);
	loadItemAttributes(pWCtx);
8->	lAAttr = getActivityAttr("AATTR");
	lIAttr = getItemAttr("IATTR");
9->	lIAttr.value((Object)"NEWVALUE");
	setItemAttrValue(pWCtx, lIAttr);
10->	}
	catch (Exception e)
	{
	es.addMessage("WF","WF_FN_ERROR");
	es.addToken("MODULE",this.getClass().getName());
	es.addToken("ITEMTYPE",itemType);
	es.addToken("ITEMKEY",itemKey);
	es.addToken("ACTID",actID.toString());
	es.addToken("FUNCMODE",funcMode);
	es.addToken("ERRMESSAGE",e.getMessage());
	return false;
	}
11->	return true;
	}
	}

1-> By default, Java classes supplied by Oracle Workflow will be in the oracle.apps.fnd.wf package. This section is optional.

2-> For correct operation, you must include the listed packages.

3-> The custom Java class must extend the WFFunctionAPI class. This class provides class variables and methods that are essential to the operation of your function activity.

The parameters that are normally supplied to a PL/SQL function activity are available to the custom class as class variables. They are initialized prior to the call of the boolean execute() method. The resultOut and the errorStack are then passed back to the Oracle Workflow Engine. The predefined class variables include:

	itemTypeThe internal name for the item type. Item types are defined in the Oracle Workflow Builder.
itemKey	A string that represents a primary key generated by the workflow-enabled application for the item type. The string uniquely identifies the item within an item type.
ActID	The ID number of the activity from which this procedure is called.
funcMode	The execution mode of the activity. For a function activity, the mode is either 'RUN' or 'CANCEL'. Other execution modes may be added in the future.
resultOut	If a result type is specified in the Activities properties page for the activity in the Oracle Workflow Builder, this parameter represents the expected result that is returned when the procedure completes. The possible results are:
	COMPLETE:<result_code>--activity completes with the indicated result code. The result code must match one of the result codes specified in the result type of the function activity.
	WAITING--activity is pending, waiting on another activity to complete before it completes. An example is the Standard 'AND' activity.
	DEFERRED:<date>--activity is deferred to a background engine for execution until a given date. <date> must be of the format:

				to_char(<date_string>, wf_engine.date_format)

	NOTIFIED:<notification_id>:<assigned_user>-- an external entity is notified that an action must be performed. A notification ID and an assigned user can optionally be returned with this result. Note that the external entity must call CompleteActivity( ) to inform the Workflow Engine when the action completes.
	ERROR:<error_code>--activity encounters an error and returns the indicated error code.

4-> The custom Java class must implement the boolean execute() method. This will be the main entry point for your Java class. On successful completion, this method should return true.

5-> It is important to catch exceptions with your custom Java class and pass them back to the engine via the ErrorStack class. Refer also to section 10.

6-> To access item and activity attributes, a WFAttribute class is provided.

7-> The values of the item attributes are not automatically available to the Java class. They are loaded on demand. The values can be loaded explicitly with the void loadItemAttributes(WFContext) or the void loadActivityAttributes(WFContext) methods. The values are also loaded implicitly when you call the WFAttribute getItemAttr(String) or WFAttribute getActivityAttr(String) methods. This section is optional.

8-> The actual values of the item and activity attributes are accessed via the WFAttribute getItemAttr(String) and WFAttribute getActivityAttr(String) methods. If you have not explicitly loaded the values of the attributes, they will be automatically loaded at this point.

9-> Setting the value of an item attribute with the void setItemAttrValue(WFContext, WFAttribute) method writes the value of your local WFAttribute to the database. You need to set the values of the WFAttribute class with the WFAttribute.value(Object) method.

10-> It is important to catch exceptions within your custom Java class and pass them back to the engine via the ErrorStack class.

An unsuccessful execution of the external Java function activity will return false.

Note that any message in the WFContext.wErrorStack class variable will be passed back to the Workflow Engine and will cause the activity to be assigned a completion status of ERROR.

11-> A successfully executed external Java function activity will return true.