Previous	Next		Contents	Index	Glossary

Note: This functionality is currently only available for the standalone version of Oracle Workflow. It is not available in Oracle Applications.

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. The WFFunctionAPI and WFAttribute classes also contain methods that your Java program can call to access item type and activity attributes. See: Oracle Workflow Java Interface, Oracle Workflow API Reference, Workflow Function APIs, Oracle Workflow API Reference, and Workflow Attribute APIs, Oracle Workflow API Reference.

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 for the function activity. 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, Oracle Workflow Administrator's Guide.

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, Oracle Workflow API Reference.

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, Oracle Workflow Administrator's Guide.

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, itemType, itemKey, actID); 

              loadItemAttributes(pWCtx); 

8->           lAAttr = getActivityAttr("AATTR"); 

              lIAttr = getItemAttr("IATTR"); 

9->           <your executable statements>

10->          lIAttr.value((Object)"NEWVALUE"); 

              setItemAttrValue(pWCtx, lIAttr); 

11->        }

              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; 

              }

12->           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 status of the completed activity will be set to COMPLETE unless a value is present in the errorStack variable. If there is a value in this variable, then the activity status will be set to ERROR. The contents of the errorStack variable can be set by using the ErrorStack class within the WFContext class. Refer also to sections 5 and 11 of this API for catching exceptions.

The predefined class variables include:

itemType	The 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. Currently the only supported mode for external Java function activities is the 'RUN' mode.
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.

Note: Unlike the resultout for a PL/SQL procedure called by a function activity, the resultOut for a Java procedure does not include a status code. In the Java API, only the result type value is required. The status of the activity will be set automatically by the Workflow Engine depending on whether there is a value in the errorStack variable.

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 11 of this API for catching exceptions.

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-> This section contains your own executable statements. Usually, you add these executable statements after retrieving the required item and activity attribute details (section 8) and before setting item attribute values (section 10).

10-> 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.

11-> 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.

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