Wednesday Jun 24, 2015

Make your workflows context dependent the right way


Oracle Workflow is context-agnostic. Oracle Workflow does not guarantee a specific application context to be available during the execution of a workflow process.

A workflow process may need certain application context to be initialized in order for a process activity to execute successfully. For example, if an activity submits a concurrent program request, it needs certain application context to be initialized.

Oracle Workflow provides ability for application code to manage application context for their workflow processes. Before executing a workflow process, it first allows to test the context. If the test determines that a specific application context should be initialized, it then allows to set the required context before continuing to execute the workflow process.

In order to manage application context from within a workflow process, Oracle Workflow supports the notion of Callback Function (popularly known as Selector Function). Hence, for a given item type a single function operates as both selector and a callback function.

  • Selector - Selects the appropriate process name to execute when the item type is initiated without specifying the process name.
  • Callback - To test and set application context required for the workflow process to execute.

Callback Function 

In this blog post we will only discuss the function modes for the Callback feature. A function mode is the condition under which the callback function implementation should do a certain processing.

  • TEST_CTX - Before executing a workflow process activity, determine if the current application context is correct for the given item type. In a typical case, the application context is evaluated by checking the values of but not limited to FND_GLOBAL.USER_ID, FND_GLOBAL.RESP_ID, FND_GLOBAL.RESP_APPL_ID and so on. These are Application Object Library (FND) global variables that determine if an appropriate application context is initialized or not.
    • NOTSET - Context has not been initialized. For example, if FND_GLOBAL.USER_ID is -1 it indicates an application context was not initialized.
    • FALSE - A context is already initialized but it is not correct for the given workflow item type. Workflow engine should switch context is allowed.
    • TRUE - A context is already initialized and it is valid for the given workflow item type.
    • Null - The item type does not depend on any context.
  • SET_CTX - Establish required application context for the item type.

Refer to Oracle Workflow Developer's Guide for Standard API for an Item Type Selector or Callback Function 

In a given session, Oracle Workflow executes the callback function each time it encounters a new item type and item key combination. For example, when a workflow process (identified by a given item type and item key) is initiated, the workflow engine executes the callback function only once before first activity. For the rest of the activities in the process, the selector function is not executed in that session. Now, in the same session if a new workflow process (identified by the same item type but a different item key) is initiated, the callback function is executed again.

Preserve Context

While it is extremely beneficial to allow application code to manage required application context during execution of a workflow process, it is also important to determine when the application context can be switched and when it cannot be. Oracle Workflow internally maintains a flag WF_ENGINE.PRESERVED_CONTEXT that determines whether context switching is allowed or not.

WARNING: This flag is INTERNAL ONLY and cannot be manipulated by the application code

Oracle Workflow initializes this flag with either TRUE or FALSE based on whether it is required to preserve the current application context or not.

  • TRUE - This value indicates that the workflow engine is required to preserve current context. This is typically when workflow engine executes in the foreground.
    • For example, if an approver signed into Worklist and approved a notification, the workflow engine executes in the foreground. Since it is required to preserve the current approver's context, workflow engine cannot switch to a different application context.
    • If the callback function returns FALSE in TEST_CTX mode, the workflow engine since it is required to preserve existing application context, it will not execute the callback function in SET_CTX mode. Instead, it will defer the workflow process to background engine that will then invoke the callback function in TEST_CTX and SET_CTX modes. 
  • FALSE - This value indicates that the workflow engine is not required to preserve current context. This is typically when the workflow engine executes in the background, such as initiated by Workflow Mailer or Workflow Background Engine concurrent request.

Following table summarizes how Oracle Workflow treats results of TEST_CTX mode in a given preserve context situation.

 TRUE  Set Context  Defer to Background Engine  No Change  No Change
 FALSE  Set Context  Set Context   No Change  No Change


It is very important to understand the nuances of context management within workflow process with regards to

  • What result to send back to workflow engine in TEST_CTX mode?
    • Clearly understand the difference between NOTSET and FALSE. They have completely different meanings and impact to workflow execution.
  • How workflow engine treats different TEST_CTX results in the context of preserve context flag?
    • Your workflow process may be deferred to workflow background engine and executed later on. If the background engine is not running, your workflow will not be executed.


Friday Aug 16, 2013

Understanding Workflow Errors - Part 2

This post is a follow up to Understanding Workflow Errors - Part 1 that deals with some of the most common errors raised when some of the Workflow Engine APIs are used. 

The way to trap and continue processing upon finding these errors is the same: evaluate the content of global variable WF_CORE.error_name.

Error message: 3103 Attribute 'ATTRIBUTE' does not exist for item 'TYPE/KEY'


The most likely reason for this to happen is a change in the Workflow definition. For instance, an attribute is added to the definition while there are open workflows  not having it. Then you attempt to set a value for it and notice new processes have no issues but the ones created before the change will fail.

Whenever possible these regressions should be foreseen and addressed in the design of the Workflow definition. A possible workaround is to add the supporting plsql code to check for the exception:

    if WF_CORE.error_name='WFENG_ITEM_ATTR' then
    end if;

Error message: 3120 Activity 'TYPE/ACTID' has no performer


All performers of notification activities are taken from view WF_ROLES. The most typical reason for this error is the originally assigned user/role has been expired. While the correct fix is to unexpire the performer and let the workflow complete, there are two possible ways to go around:

1. Change the value to the attribute holding the name of the performer. For instance, if there is an item attribute RECIPIENT pointing to expired user JSMITH then change it to an active user/role, say JHOPKINS. You will need to call this from a SQL*Plus session:

   WF_ENGINE.SetItemAttrText(<type>, <key>, 'RECIPIENT', 'JHOPKINS');

2. The other alternative is to change all references in ALL the workflow runtime tables to change anything related to JSMITH and change it to the taking over user JHOPKINS:

  l_attributes wf_parameter_list_t;
  WF_EVENT.AddParameterToList('OLD_USER_NAME', 'JSMITH', l_attributes);
  WF_EVENT.AddParameterToList('USER_NAME', 'JHOPKINS', l_attributes);
  WF_LOCAL_SYNCH.Propagate_Role(p_orig_system    => <orig system>, --for instance, 'FND_USR' or 'PER'
                                p_orig_system_id => l_orig_system_id, --for instance, 29984
                                p_attributes     => l_attributes);

As always, use care and try these APIs on a test environment before using them in production

Error message: 3133 Activity instance 'NAME' is not a notified activity for item 'TYPE/KEY'.


When it is needed that the processing of a workflow stops to wait for something to happen a BLOCK function can be used. When the block function runs the activity goes into NOTIFIED status. Then, to resume the processing, an explicit call to WF_ENGINE.CompleteActivity must be made. But if the activity is not in notified status then the API will raise WFENG_NOT_NOTIFIED.

There is no straightforward action to deal with this error. Rather, troubleshooting must be made to see why the activity did not go into NOTIFIED status. Sometimes the reason is that the workflow process continued to the next activity, leaving it complete or did not even reach it. A good way to understand what the workflow process has done is to run the seeded script wfstat.sql. Check the output and follow the execution path.



« June 2016