Copyright © Cloud Software Group, Inc. All Rights Reserved
Copyright © Cloud Software Group, Inc. All Rights Reserved


Appendix A Deprecated Callout Interface : Callout Interface
Callout Interface
The callout interface provides methods that allow you to:
•
Set default filters and sorts on the work item and case lists.
•
Specify filters and sorts that can modify any user-defined filters and sorts.
•
Specify which columns/fields the user can filter and sort on for work item and case lists.
•
Set default columns to display on the procedure list, work queue list, case list, work item list, outstanding work item list on the case Outstanding tab, and the outstanding work item list on the Process Jump dialog.
•
Specify which columns are available for a user to display from the Column Selector dialogs.
Methods in the callout interface can be used in combination with user access profile settings to control filter, sort, and column display. For example:
•
You could use the callout interface methods to set a default filter on the case list, then use the access profiles to not allow the user to set a filter (i.e., do not give access to the case list Filter dialog).
•
You could use the callout interface methods to display specific columns in the work item list by default, then use the user access profiles to not allow the user to change the columns (i.e., do not give access to the Column Selector on the work item list).
For information about user access profiles, see User Access.
Since callout method calls are used to restrict access to data, any exceptions thrown will prevent the associated list from loading or close an already open list. An error message will be displayed to the user, logged to the Application Log and Application Monitor, and the list will be closed.
The callout methods are arranged in three functional groups:
•
Filter - These methods control default filters and additional filters to apply to user-defined filters.
•
Sort - These methods control default sorts and additional sorts to apply to user-defined sorts.
•
Column - These methods control default column displays and which columns the user is allowed to select from the Column Selector.
* 
Basic knowledge of XML, JavaScript, and TIBCO General Interface is necessary to understand and work with the callout methods.
The following tables show the callout methods available:
Filter Methods (Case and Work Item Lists)
Method
Description
calloutInitialWorkItemFilter
Specifies the filter to be used when the work item list is opened. The filter that was saved when the list was last closed can be reused with or without modifications, or it can be replaced with a default filter. This filter appears on the Filter dialog after it is applied, and can be changed by the user if they have access to the Filter dialog.
calloutWorkItemFilter
Specifies the filter to apply to the work item list. This may be used to either modify the user-defined filter, to append additional criteria, or to override it. This is applied automatically when the user applies a filter by either clicking the Apply button on the work item list Filter dialog, or by applying a server-side find. Any user-defined filter will appear on the Filter dialog, but any modification applied to the filter with this method will not be visible to the user.
calloutWorkItemFilterColumns
Specifies which fields/columns can be used to filter work items, i.e., it controls which fields/columns appear in the Field drop-down list on the Filter dialog.
calloutInitialCaseFilter
Specifies the filter to be used when the case list is opened. The filter that was saved when the list was last closed can be reused with or without modifications, or it can be replaced with a default filter. This filter appears on the Filter dialog after it is applied, and can be changed by the user if they have access to the Filter dialog.
calloutCaseFilter
Specifies the filter to apply to the case list. This may be used to either modify the user-defined filter, to append additional criteria, or to override it. This is applied automatically when the user applies a filter by clicking the Apply button on the case list Filter dialog. Any user-defined filter will appear on the Filter dialog, but any modification applied to the filter with this method will not be visible to the user.
calloutCaseFilterColumns
Specifies which fields/columns can be used to filter cases, i.e., it controls which fields/columns appear in the Field drop-down list on the Filter dialog.
Sort Methods (Case and Work Item Lists)
Method
Description
calloutInitialWorkItemSort
Specifies the sort to be used when the work item list is opened. The sort that was saved when the list was last closed can be reused with or without modifications, or it can be replaced with a default sort. This sort appears on the Sort dialog after it is applied, and can be changed by the user if they have access to the Sort dialog.
calloutWorkItemSort
Specifies the sort to apply to the work item list. This may be used to either modify the user-defined sort, to append additional criteria, or to override it. This is applied automatically when the user applies a sort by clicking the Apply button on the work item list Sort dialog. Any user-defined sort will appear on the Sort dialog, but any modification applied to the sort with this method will not be visible to the user.
calloutWorkItemSortColumns
Specifies which fields/columns can be used to sort work items, i.e., it controls which fields/columns appear in the Available Fields list on the Sort dialog.
calloutInitialCaseSort
Specifies the sort to be used when the case list is opened. The sort that was saved when the list was last closed can be reused with or without modifications, or it can be replaced with a default sort. This sort appears on the Sort dialog after it is applied, and can be changed by the user if they have access to the Sort dialog.
calloutCaseSort
Specifies the sort to apply to the case list. This may be used to either modify the user-defined sort, to append additional criteria, or to override it. This is applied automatically when the user applies a sort by clicking the Apply button on the case list Sort dialog. Any user-defined sort will appear on the Sort dialog, but any modification applied to the sort with this method will not be visible to the user.
calloutCaseSortColumns
Specifies which fields/columns can be used to sort cases, i.e., it controls which fields/columns appear in the Available Fields list on the Sort dialog.
Column Methods (Procedure, Case, Work Queue, Work Item, Outstanding, Outstanding-Jump Lists)
Method
Description
calloutColumns
Specifies the default columns to display on the procedure list, case list, work queue list, work item list, outstanding work items list on the case Outstanding tab, and the outstanding work items lists on the Process Jump dialog.
calloutSelectColumns
Specifies which columns will be available to the user on the Column Selector dialog from the procedure list, case list, work queue list, work item list, outstanding work items list on the case Outstanding tab, and the outstanding work items lists on the Process Jump dialog. This controls which columns the user is able to display on each of the lists.
A custom class can implement one or more of the methods in the tables above. One or more custom classes may be used to handle these method calls.
If there is no implementation of these methods, there are no restrictions other than what might be applied through user access profiles.
Additional details about each callout method can be found in Callout Method Signatures.
* 
Also see the Migration section in the Release Notes for information about callout interface method considerations if you are upgrading your version of the iProcess Workspace (Browser).
Configuration
The TIBCO iProcess Workspace (Browser) comes with a sample callout handler that contains sample implementations of all of the callout methods. This sample callout handler is named ‘SampleCalloutHandler.js’ and is located in the InstallationHomeDir\iprocessclientbrowser\samples\Callouts directory, where InstallationHomeDir is the directory in which the installer places administrative files, such as the uninstaller, documentation, and sample code. This defaults to C:\tibco on Windows systems, and /opt/tibco on UNIX systems, but can be specified as a different directory when the iProcess Workspace (Browser) is installed.
* 
Upon deprecation of this callout interface, the name of the sample callout handler file was renamed SampleCalloutHandlerDeprecated.js. For more information, see page 421.
Perform the following steps to create a custom handler and configure your iProcess Workspace (Browser) to use the callout methods.
1.
Copy the SampleCalloutHandler.js file into a directory you’ve created under the ClientInstallDir\JSXAPPS\ipc\ directory, where ClientInstallDir is the path to the directory in which the iProcess Workspace (Browser) is installed. For example, ClientInstallDir\JSXAPPS\ipc\Callouts.
You may also want to rename the SampleCalloutHandler.js file to identify the type of custom handling it performs. For example, ‘ColumnsCalloutHandler.js’.
2.
Modify the callout handler (e.g., ColumnsCalloutHandler.js) to fit your needs.
The original SampleCalloutHandler.js file that you copied contains sample implementations of each of the available callout methods.
Each callout method receives a data parameter that can be modified by the method and returned to the application. The following are example data parameters:
−
filterExpression (string)
−
sortFields (Array<com.tibco.bpm.ipc.vSortField>)
−
columns (jsx3.xml.Entity)
Additional parameters provide information the methods can use to determine how the filters, sorts, and columns should be modified. For example:
−
username (string)
−
eventNode (jsx3.xml.Entity)
−
listType (string)
−
availableFields (jsx3.xml.Entity)
There is also a componentName parameter that specifies the specific instance of the component the method is affecting. This can be useful in WCC custom applications where you may be displaying multiple lists at one time, and would like to modify the filter, sort, or columns on only one of them.
The jsx3.xml.Entity object is a TIBCO General Interface class that is a wrapper of the native browser XML node class. This class provides methods for querying, traversing, and creating XML entities (see the TIBCO General Interface documentation for more information). The object is a Document Object Model (DOM) class that provides methods to add, find, modify, or delete XML values in an XML document. Use these methods to modify the incoming XML so that the desired filter, sort, or columns are displayed.
In each case, the method returns the same type of XML object that was passed in. This would probably be the same object in most cases, with some modification applied.
When customizing the callout handler, you must also register the callout method with the application CalloutController by adding the method to the init (constructor) method. It must be in the form:
    app.getCalloutController().registerHandler(target,arrayOfMethodNames)
where:
−
target - (Object) The instance or object the method is called on.
−
arrayOfMethodNames - (Array<strings>) Array of strings that are the names of the methods to register.
The following is an example of the init method in which the calloutColumns method is registered:
 
ipcClass.prototype.init = function(app) {
   this.app = app;
   this.controller = this.app.getCalloutController();
   this.controller.registerHandler(this,['calloutColumns']);
};
 
A reference to the application object is passed as the single parameter to the init (constructor) method.
Note that the application getServer() method can be used to get a reference to the jsx3.app.Server instance:
   app.getServer()
3.
Specify the callout handler custom class in the iProcess Workspace (Browser)’s configuration file, ClientInstallDir\JSXAPPS\ipc\config.xml.
The <record jsxid=”customCallout” element specifies which classes will be loaded to handle custom callout methods. The <Classes> element can contain any number of <Class> elements whose class attribute is set to the fully qualified name of the custom class to load. The class is loaded after the user is authenticated at login. This gives the custom class access to the logged-in user's session to query the Action Processor for initialization data, if required.
The following is an example of the customCallout element identifying the ColumnsCalloutHandler custom class:
 
   <record jsxid="customCallout" type="ipc">
      <Classes>
         <Class class="com.tibco.bpm.ipc.ColumnsCalloutHandler" />
      </Classes>
   </record>
 
4.
Add a mapping record to the config.xml file that points to the custom handler. This is added as a child element of the <record jsxid=”includes” element. The following is an example class mapping element for the custom callout handler, ColumnsCalloutHandler.js.
 
<record jsxid="includes" type="array">
   ...
   <record jsxid="90" type="map">
      <record jsxid="id" type="string">ColumnsCalloutHandler</record>
      <record jsxid="type" type="string">script</record>
      <record jsxid="owner" type="string">application</record>
      <record jsxid="onLoad" type="boolean">true</record>
      <record jsxid="required" type="boolean">true</record>
       <record jsxid="src" type="string">JSXAPPS/ipc/Callouts/ColumnsCalloutHandler.js</record>
   </record>
</record>
 
5.
Optionally, modify the user access profiles that would be used in conjunction with the custom handling. For example, if your custom handler is setting the default columns on the work item list, you may want to deny access to the Column Selector on the work item list (see SelectColumns on page 17).
* 
Note that case is significant on some web servers, such as Tomcat. For example, if you are storing your custom callouts in the directory, ClientInstallDir\JSXAPPS\ipc\Callouts (i.e., with “Callouts” capitalized), the path specification to the custom callout handler in the config.xml file cannot be “JSXAPPS/ipc/callouts/ColumnsCalloutHandler.js” (i.e., with “callouts” not capitalized).
Callout Method Signatures
The following are the method signatures from the SampleCalloutHandler.js file (in JavaDoc format).
Note that the parameter data XML examples shown with the method signatures are representative samples — they may contain other attributes that are not shown.
calloutInitialWorkItemFilter
 
/**
* @param filterExpression (string) The filter string value.
* @param username (string) The logged in user name.
* @param queueNode (jsx3.xml.Entity) The queue node XML for the
* workitem list.
* @param availableFields (jsx3.xml.Entity) XML defining the available
* fields that can be filtered.
         * @param componentName (string) Component instance name
*
* @return (string) Modified filter string.
*/
ipcClass.prototype.calloutInitialWorkItemFilter = function(
filterExpression,
username, queueNode,
availableFields
                                                            componentName) {
 
calloutWorkItemFilter
 
/**
* @param filterExpression (string) The filter string value.
* @param username (string) The logged in user name.
* @param queueNode (jsx3.xml.Entity) The queue node XML for the
* workitem list.
* @param availableFields (jsx3.xml.Entity) XML defining the available
* fields that can be filtered.
         * @param componentName (string) Component instance name
*
* @return (string) Modified filter string.
*/
ipcClass.prototype.calloutWorkItemFilter = function(filterExpression,
username, queueNode,
availableFields
                                                            componentName) {
 
The following is an example filterExpression parameter value used with calloutWorkItemFilter:
SW_PRONAME = "a*"
The sample above would show only work items whose procedure name starts with “a”. (For information about filter expression syntax, see the TIBCO iProcess Server Objects (Java or .NET) Programmer’s Guide.)
calloutWorkItemFilterColumns
 
/**
* @param availableFields (jsx3.xml.Entity) XML defining the available
* fields that can be filtered.
* @param username (string) The logged in user name.
* @param queueNode (jsx3.xml.Entity) The queue node XML for the
* workitem list.
         * @param componentName (string) Component instance name
         *
* @return                (jsx3.xml.Entity) Modified XML defining the          *                                          available fields that can be          *                                          filtered.
*/
ipcClass.prototype.calloutWorkItemFilterColumns = function(
availableFields,
username,
queueNode
                                                            componentName) {
 
The following are example availableFields and queueNode parameter values used with calloutWorkItemFilterColumns:
 
availableFields (jsx3.xml.Entity)
 
 
 
queueNode (jsx3.xml.Entity)
 
calloutInitialCaseFilter
 
/**
* @param filterExpression (string) The filter string value.
* @param username (string) The logged in user name.
* @param procNode (jsx3.xml.Entity) The procedure node XML for
* the case list.
* @param availableFields (jsx3.xml.Entity) XML defining the available
* fields that can be sorted.
         * @param componentName (string) Component instance name
*
* @return (string) Modified filter string.
*/
ipcClass.prototype.calloutInitialCaseFilter = function(
filterExpression,
username, procNode,
availableFields
                                                            componentName) {
 
 
calloutCaseFilter
 
/**
* @param filterExpression (string) The filter string value.
* @param username (string) The logged in user name.
* @param procNode (jsx3.xml.Entity) The procedure node XML for
* the case list.
* @param availableFields (jsx3.xml.Entity) XML defining the available
* fields that can be filtered.
         * @param componentName (string) Component instance name
*
* @return (string) Modified filter string.
*/
ipcClass.prototype.calloutCaseFilter = function(filterExpression,
username, procNode,
availableFields
                                                            componentName) {
 
 
calloutCaseFilterColumns
 
/**
* @param availableFields (jsx3.xml.Entity) XML defining the available
* fields that can be filtered.
* @param username (string) The logged in user name.
* @param procNode (jsx3.xml.Entity) The proc node XML for the
* case list.
         * @param componentName (string) Component instance name
         *
* @return                (jsx3.xml.Entity) Modified XML defining the          *                                          available fields that can be          *                                          filtered.
         */
ipcClass.prototype.calloutCaseFilterColumns = function(availableFields,
username,
procNode
                                                            componentName) {
 
 
calloutInitialWorkItemSort
 
/**
* @param sortFields (Array) An array of
* com.tibco.bpm.ipc.vSortField
* instances.
* @param username (string) The logged in user name.
* @param queueNode (jsx3.xml.Entity) The queue node XML for the
* workitem list.
* @param availableFields (jsx3.xml.Entity) XML defining the available
* fields that can be sorted.
         * @param componentName (string) Component instance name
*
* @return (Array) Modified array of
* com.tibco.bpm.ipc.vSortField
* instances.
*/
ipcClass.prototype.calloutInitialWorkItemSort = function(sortFields,
username, queueNode,
availableFields
                                                            componentName) {
 
 
calloutWorkItemSort
 
/**
* @param sortFields (Array) An array of
* com.tibco.bpm.ipc.vSortField
* instances.
* @param username (string) The logged in user name.
* @param queueNode (jsx3.xml.Entity) The queue node XML for the
* workitem list.
* @param availableFields (jsx3.xml.Entity) XML defining the available
* fields that can be sorted.
         * @param componentName (string) Component instance name
*
* @return (Array) Modified array of
* com.tibco.bpm.ipc.vSortField
* instances.
*/
ipcClass.prototype.calloutWorkItemSort = function(sortFields,
username, queueNode,
availableFields
                                                            componentName) {
 
The following describes the sortFields parameter used with calloutWorkItemSort:
Each vSortField has three properties with accessors as shown:
−
fieldName getFieldName()
−
ascending getAscending()
−
sortAsType getSortAsType()
For example:
sortFields[0] :
fieldName : SW_CASEDESC
ascending : true
sortAsType: swTextSort
sortFields[1] :
fieldName : SW_CASENUM
ascending : true
sortAsType: swTextSort
Work items will be sorted in the order in which elements are passed in the vSortField array.
New vSortField values are created by passing the three properties in the constructor:
var newSortFields = new Array();
newSortFields.push(new com.tibco.bpm.ipc.vSortField('SW_CASEDESC',
                             true,
                             'swTextSort'));
newSortFields.push(new com.tibco.bpm.ipc.vSortField('SW_CASENUM',
                             true,
                             'swTextSort'));
calloutWorkItemSortColumns
 
/**
* @param availableFields (jsx3.xml.Entity) XML defining the available
* fields that can be sorted.
* @param username (string) The logged in user name.
* @param queueNode (jsx3.xml.Entity) The queue node XML for the
* workitem list.
         * @param componentName (string) Component instance name
         *
* @return                (jsx3.xml.Entity) Modified XML defining the          *                                          available fields that can be          *                                          filtered.
         */
ipcClass.prototype.calloutWorkItemSortColumns = function(
availableFields,
username,
queueNode
                                                            componentName) {
 
The following is an example availableFields parameter value used with calloutWorkItemSortColumns:
calloutInitialCaseSort
 
/**
* @param sortFields (Array) An array of
* com.tibco.bpm.ipc.vSortField
* instances.
* @param username (string) The logged in user name.
* @param procNode (jsx3.xml.Entity) The procedure node XML for
* the case list.
* @param availableFields (jsx3.xml.Entity) XML defining the available
* fields that can be sorted.
         * @param componentName (string) Component instance name
*
* @return (Array) Modified array of
* com.tibco.bpm.ipc.vSortField
* instances.
*/
ipcClass.prototype.calloutInitialCaseSort = function(sortFields,
username, procNode,
availableFields
                                                            componentName) {
 
calloutCaseSort
 
/**
* @param sortFields (Array) An array of
* com.tibco.bpm.ipc.vSortField
* instances.
* @param username (string) The logged in user name.
* @param procNode (jsx3.xml.Entity) The procedure node XML for
* the case list.
* @param availableFields (jsx3.xml.Entity) XML defining the available
* fields that can be sorted.
         * @param componentName (string) Component instance name
*
* @return (Array) Modified array of
* com.tibco.bpm.ipc.vSortField
*
*/
ipcClass.prototype.calloutCaseSort = function(sortFields,
username, procNode,
availableFields
                                                            componentName) {
 
 
calloutCaseSortColumns
 
/**
* @param availableFields (jsx3.xml.Entity) XML defining the available
* fields that can be sorted.
* @param username (string) The logged in user name.
* @param procNode (jsx3.xml.Entity) The proc node XML for the
* case list.
         * @param componentName (string) Component instance name
         *
* @return                (jsx3.xml.Entity) Modified XML defining the          *                                          available fields that can be          *                                          filtered.
         */
ipcClass.prototype.calloutCaseSortColumns = function(availableFields,
username,
procNode
                                                            componentName) {
 
 
calloutColumns
 
/**
* @param columns (jsx3.xml.Entity) The serialized columns for
* the list.
* @param username (string) The logged in user name.
* @param eventNode (jsx3.xml.Entity) The procedure (Cases list),
* workQ (WorkItems list), or
* caseTag data (Outstanding)
* node XML. Null for Proc and
* WorkQ list types:
* @param availableFields (jsx3.xml.Entity) XML defining the available
* fields for column selection.
* @param listType (string) The list type, one of:
* com.tibco.bpm.ipc.ListContainer.PROC
* com.tibco.bpm.ipc.ListContainer.CASE
* com.tibco.bpm.ipc.ListContainer.WORKQ
* com.tibco.bpm.ipc.ListContainer.WORKITEM
* com.tibco.bpm.ipc.ListContainer.OUTSTANDING
* com.tibco.bpm.ipc.ListContainer.OUTSTANDING + 'Jump'
         * @param componentName (string) Component instance name
*
* @return (jsx3.xml.Entity) Modified serialized columns
* for the list.
*
*/
ipcClass.prototype.calloutColumns = function(columns,
username, eventNode,
availableFields,
listType
                                                            componentName) {
 
The following describes the eventNode parameter used with calloutColumns:
The value of eventNode depends on the type of list as shown below:
−
Proc list : null
−
Case list:
−
WorkQ list: null
−
WorkItem list:
−
Outstanding or Outstanding Jump:
 
calloutSelectColumns
 
/**
* @param availableFields (jsx3.xml.Entity) XML defining the fields
* available for column
* selection.
* @param username (string) The logged in user name.
* @param eventNode (jsx3.xml.Entity) The procedure (Cases list),
* workQ (WorkItems list), or
* caseTag data (Outstanding)
* node XML. Null for Proc and
* WorkQ list types:
* @param columns (jsx3.xml.Entity) The serialized columns for
* the list.
* @param listType (string) The list type, one of:
* com.tibco.bpm.ipc.ListContainer.PROC
* com.tibco.bpm.ipc.ListContainer.CASE
* com.tibco.bpm.ipc.ListContainer.WORKQ
* com.tibco.bpm.ipc.ListContainer.WORKITEM
* com.tibco.bpm.ipc.ListContainer.OUTSTANDING
* com.tibco.bpm.ipc.ListContainer.OUTSTANDING + 'Jump'
         * @param componentName (string) Component instance name
*
* @return (jsx3.xml.Entity) Modified XML defining the
* fields available for column
* selection.
*
*/
ipcClass.prototype.calloutSelectColumns = function(availableFields,
username, eventNode,
columns,
listType
                                                            componentName) {
 
The following are example availableFields and columns parameter values used with calloutSelectColumns:
availableFields (jsx3.xml.Entity)
 
columns (jsx3.xml.Entity)
The columns value contains the serialized columns for the list. The following sample shows how this can be obtained from a jsx3.gui.List:
var objProperties = new Object();
 
objProperties['children'] = true;
 
var serializedXml = jsxList.toXML(objProperties);
The following is a sample of the serialized columns:
 
Copyright © Cloud Software Group, Inc. All Rights Reserved
Copyright © Cloud Software Group, Inc. All Rights Reserved