Guest Status Monitor access provides tightly coupled access from an Oracle Application Framework-based Web page or Oracle E-Business Suite form, to a freestanding Status Monitor page for a particular workflow, without access to the rest of the Oracle Workflow application. In this mode, the specified Status Monitor page is displayed without the full Oracle Workflow menu, so that users cannot navigate out of the Status Monitor to other Oracle Workflow pages.

Guest access lets users navigate among the top-level Status Monitor pages, including the Activity History page in the Administrator Monitor or Notification History page in the Self-Service Monitor, Status Diagram page, Monitor Responses page, and Workflow Details page. Users can also drill down from the top-level pages to related detail or action pages, such as navigating from the Notification History page to the Cancel page. Additionally, locator links, also known as breadcrumbs, let users navigate from the Status Monitor back to the calling application. However, users cannot navigate from the Status Monitor to other parts of Oracle Workflow.

With guest access, users are fully authenticated. However, in this mode you programmatically control which workflow process users can view and whether users can perform administrative operations in the Status Monitor, rather than having these privileges controlled by the workflow administrator setting in the Workflow Configuration page.

When you provide guest access to the Status Monitor from your application, you must specify a workflow item type and item key to automatically query. Guest access does not include search capabilities, so users can only view the workflow process you specify. You can choose to initially display the specified workflow in either the Activity History page in the Administrator Monitor or Notification History page in the Self-Service Monitor, the Status Diagram page, or the Monitor Responses page. If you do not specify an initial page, the workflow is initially displayed in the Activity History page in the Administrator Monitor or Notification History page in the Self-Service Monitor.

You must also set the administrator mode to determine whether to grant the user privileges to perform administrative operations within the Status Monitor. You can choose one of the following options:

• Never grant administrator privileges, regardless of whether the user belongs to the workflow administrator role specified in the Workflow Configuration page. This option is the default if you do not specify an administrator mode.

• Always grant administrator privileges, regardless of whether the user belongs to the workflow administrator role specified in the Workflow Configuration page.

• Check whether the user belongs to the workflow administrator role specified in the Workflow Configuration page and grant administrator privileges accordingly.

Oracle Workflow provides Java methods to obtain URLs for guest access to the Status Monitor. These methods are defined in the Java class called oracle.apps.fnd.wf.monitor.webui.Monitor.

• Monitor.redirectToGuestAdvUrl( ) - Redirects to the Administrator Monitor with guest access.

• Monitor.redirectToGuestSimpleUrl( ) - Redirects to the Self-Service Monitor with guest access.

• Monitor.getGuestAdvanceUrl( ) - Returns a URL for guest access to the Administrator Monitor, in a form that can be used within an Oracle Application Framework application page. For example, you can set this URL as a destination link on an OAWebBean. The URL is returned in the following format:

  /OA_HTML/OA.jsp?OAFunc=[parameters...]
  

• Monitor.getGuestSimpleUrl( ) - Returns a URL for guest access to the Self-Service Monitor, in a form that can be used within an Oracle Application Framework application page. For example, you can set this URL as a destination link on an OAWebBean. The URL is returned in the following format:

  /OA_HTML/OA.jsp?OAFunc=[parameters...]
  

When calling these methods, you must provide the following parameters to indicate how you want to display the Status Monitor:

• pageContext - The OAPageContext of the calling page.

• itemType - The internal name of a workflow item type to automatically query in the Status Monitor.

• itemKey - An item key to automatically query in the Status Monitor.

• adminMode - Specify 'Y' to grant administrator privileges to the user accessing the Status Monitor, 'N' to withhold administrator privileges from the user, or 'U' to check whether the user belongs to the workflow administrator role specified in the Workflow Configuration page and grant administrator privileges accordingly. The default is 'N'.

• firstPage - The Status Monitor page that you want to initially display.

  • HISTORY - Activity History page in the Administrator Monitor or Notification History page in the Self-Service Monitor

  • DIAGRAM - Status Diagram page

  • RESPONSES - Monitor Responses page

  The default is HISTORY.

• retainCallingAM - Specify true or false to indicate whether the OAApplicationModule of the calling page should be retained while working in the Status Monitor. If you specify true, retainAM=Y is appended to the Status Monitor URL; if you specify false, retainAM=N is appended to the URL. The default is true.

All method calls for guest access should be made from within an Oracle Application Framework-based Web page.

The following code excerpt shows an example of how to provide guest access to the Status Monitor in Java code. This example calls the getGuestAdvanceUrl() method in the oracle.apps.fnd.wf.monitor.webui.Monitor class.

/*****************************************************************
**
** Guest Access
**
** Assumes all method calls are made from within an Oracle  
** Application Framework page.
**
*****************************************************************/

...
import oracle.apps.fnd.wf.monitor.webui.Monitor;
...

  // This example assumes we want to set the destination link on 
  // an OA text bean.Following the link will take the user to the 
  // advanced monitor on the "Activity History" page. 
  
  public void processRequest(OAPageContext pageContext, 
                             OAWebBean webBean)
  {
    super.processRequest(pageContext, webBean);

 ...

      String itemType = [ however this value is obtained in page ];
      String itemKey = [ however this value is obtained in page ];
      String firstPage = "HISTORY";
      String returnToLabel = "Return to Application XYZ";

      // Set to "U" to have Monitor code figure out if the current
      // user should have Workflow Administrator privileges based 
      // on the Administrator role designation in Workflow.

      String adminMode = "U"; 

      // Will add a parameter "retainAM=Y" to the resulting url
      // so the developer doesn't have to do this manually if he 
      // wants to retain the calling Application Module when the 
      // user navigates to the Status Monitor.

      boolean retainCallingAM = true; 

    String url = null;

    try
    {
      url = Monitor.getGuestAdvanceUrl(pageContext, itemType, 
                                  itemKey, adminMode, firstPage,
                                  returnToLabel, retainCallingAM);
    }
    catch (MonitorURLException me)
    {
      // Handle not being able to obtain a valid redirectUrl for 
      // the parameters.
    } 

    // Set the url string on the web bean.

    OAStaticStyledTextBean monitorLink = 
      (OAStaticStyledTextBean)findIndexedChildRecursive
      ("AdvancedMonitorLink");
    monitorLink.setDestination(url);

    ... 

  } // end processRequest()

Oracle Workflow also provides PL/SQL functions to obtain URLs for guest access to the Administrator Monitor. These functions are defined in the PL/SQL package called WF_MONITOR. See: Workflow Monitor APIs.

• WF_MONITOR.GetAdvancedEnvelopeURL( ) - Returns a complete URL for guest access to the Activity History page in the Administrator Monitor.

• WF_MONITOR.GetDiagramURL( ) - Returns a complete URL for guest access to the Status Diagram page in the Administrator Monitor.

• WF_MONITOR.GetEnvelopeURL( ) - Returns a complete URL for guest access to the Monitor Responses page in the Administrator Monitor.

When calling these methods, you must provide the following parameters to indicate how you want to display the Status Monitor:

• x_agent - This parameter is no longer used. Set this parameter to null.

• x_item_type - The internal name of a workflow item type to automatically query in the Status Monitor.

• x_item_key - An item key to automatically query in the Status Monitor.

• x_admin_mode - Specify 'YES' to grant administrator privileges to the user accessing the Status Monitor, or 'NO' to withhold administrator privileges from the user. The default is 'NO'.

You can use these URLs to provide access to the Administrator Monitor from a PL/SQL application, for example, or include a URL in a workflow notification message to allow a user to access the Administrator Monitor from the notification.

You can provide guest access to the Administrator Monitor from a workflow notification. To do so, define a message attribute of type URL, and include or attach this attribute in the notification message. Obtain a guest access URL using one of the WF_MONITOR PL/SQL functions, and set the value of the message attribute to this URL. The user who receives the notification can access the Administrator Monitor by viewing the notification, either through the Worklist Web pages or through an e-mail application, and clicking the link in the message. If users are not already logged into Oracle E-Business Suite, they must first log in before they can access the Administrator Monitor from the link. See: To Define a Message Attribute.

You can provide guest access from an Oracle E-Business Suite application to the Status Monitor by using self-service functions. You can call these functions from an Oracle E-Business Suite form, or add the menus that contain the functions to another menu associated with another responsibility.

The following table lists the functions that provide guest access to the Status Monitor.

Guest Access Functions

When you call one of the guest access functions, you must pass the function the following parameters:

• itemType - A valid workflow item type, determined by your application. The item type and item key together identify the workflow process to display. You must specify the same item type as you used to obtain the encrypted access key. You should use the ICX_CALL.Encrypt() function to encrypt this value.

• itemKey - A valid item key, determined by your application. The item type and item key together identify the workflow process to display. You must specify the same item key as you used to obtain the encrypted access key. You should use the ICX_CALL.Encrypt() API to encrypt this value.

• wm - The encrypted administrator mode that determines whether the user should have privileges to perform administrative operations in the Status Monitor. Call the PL/SQL function WF_FWKMON.GetEncryptedAdminMode() to obtain the encrypted value for the administrator mode you want, either Y or N. You must specify the same administrator mode value to encrypt as you used to obtain the encrypted access key. See: GetEncryptedAdminMode.

• wa - An encrypted access key for a specified item type, item key, and administrator mode combination. Call the PL/SQL function WF_FWKMON.GetEncryptedAccessKey() to obtain this value for the item type, item key, and administrator mode you want. See: GetEncryptedAccessKey.

  Note: Because users are authenticated in guest access, you can call the PL/SQL function WF_FWKMON.IsMonitorAdministrator() to determine whether a the user has administrator privileges based on the workflow administrator setting in the Workflow Configuration page. If you use this function, you should use its result when obtaining both the encrypted access key and the encrypted administrator mode, in order to avoid a discrepancy between these two values. See: IsMonitorAdministrator.

  You can also choose to grant or withhold administrator privileges in the Status Monitor by specifying the administrator mode as Y or N, respectively, regardless of the workflow administrator setting in the Workflow Configuration page.

• retainAM - Specify Y or N to indicate whether the OAApplicationModule of the calling page should be retained while working in the Status Monitor.

• fExt - An external flag used within Oracle Workflow. Set this parameter to X.

You can call the function FND_FUNCTION.EXECUTE to execute a guest access function specifying your parameters. See: FND_FUNCTION.EXECUTE.

The following code example demonstrates how to execute the WF_G_ACTIVITIES function using FND_FUNCTION.EXECUTE.

itemType := icx_call.encrypt('<your_item_type>'); 

itemKey := icx_call.encrypt('<your_item_key>'); 

adminMode := wf_fwkmon.isMonitorAdministrator('<user_name>');

wm := wf_fwkmon.getEncryptedAdminMode(adminMode); 

wa := wf_fwkmon.getEncryptedAccessKey('<your_item_type>', 
     '<your_item_key>', adminMode); 

FND_FUNCTION.EXECUTE( 
   FUNCTION_NAME => 'WF_G_ACTIVITIES', 
   OPEN_FLAG => 'Y', 
   SESSION_FLAG => 'Y', 
   OTHER_PARAMS => 
     'itemType='||(wfa_html.conv_special_url_chars(itemType))
     ||'&'||'itemKey='||(wfa_html.conv_special_url_chars(itemKey))
     ||'&'||'wm='||(wfa_html.conv_special_url_chars(wm))
     ||'&'||'wa='||(wfa_html.conv_special_url_chars(wa))
     ||'&'||'retainAM=Y'
     ||'&'||'fExt=X'
   ); 

See: Overview of Form Development Steps and Menus Window.

Menu Setup

If you use a guest access function within your responsibility, you must add the menu containing that function to the top-level menu for your responsibility. The WF_G_ACTIVITIES and WF_G_DIAGRAM functions are seeded on the Workflow Guest Monitor Application (WF_G_MONITOR_APPLICATION) menu, and the WF_SSG_ACTIVITIES and WF_SSG_DIAGRAM functions are seeded on the Workflow Guest Self-Service Monitor Application (WF_SSG_MONITOR_APPLICATION) menu.

The Workflow Guest Monitor Application menu is seeded on the Workflow Administrator (New) menu (FND_WFADMIN_NEW) associated with the Workflow Administrator Web (New) responsibility. Similarly, the Workflow Guest Self-Service Monitor Application menu is seeded on the Workflow User (New) menu (FND_WFUSER_NEW) associated with the Workflow User Web (New) responsibility.

Migrating to Guest Access Functions

If your application used self-service functions to provide access to the previous version of the Workflow Monitor, you can migrate to the new Status Monitor by replacing the functions you previously called with the appropriate new functions. The following table shows the correspondence between functions for the previous Workflow Monitor and the guest access functions for the new Status Monitor.

Migrating to Guest Access Functions