Callout Handler Configuration

You must configure your system to use the callout interface.

Procedure

Copy the following directory:
```
StudioHome\wcc\version\Samples\Callouts\
```
where:
- StudioHomeis the directory in which TIBCO Business Studio was installed.
- version is the version number of Workspace that was installed with TIBCO Business Studio.
Note: The path shown above is in the context of a custom WCC application in a TIBCO Business Studio development environment. If you want to implement callouts in the Workspace application that is pre-deployed to a BPM runtime machine, substitute the StudioHome\wcc\version\ portion of the path shown above with the following path in all steps in the Configuration section:
```
%config_home%\tibcohost\Admin-environmentName-adminServer\data_3.2.x\host\plugins\com.tibco.n2.rtc.ws_Version\resources\
```
where:
- %config_home% is the root directory for BPM runtime files. This can be specified during the installation. On Windows systems, this defaults to: C:\ProgramData\amx-bpm\tibco\data; on UNIX systems, this defaults to: /opt/tibco/data
- environmentName - The name of the BPM environment. This can be specified during the installation.
- adminServer - The name of the TIBCO Administrator server. This can be specified during the installation.
- Version is the specific version of the Workspace software installed.
Paste the ...\Samples\Callouts\ directory that you copied in step 1 into the following directory:
```
StudioHome\wcc\version\JSXAPPS\
```
where:
- StudioHome is the directory in which TIBCO Business Studio was installed.
- version is the version number of Workspace that was installed with TIBCO Business Studio
Optionally rename the CalloutHandler.js file something more specific if that's what its purpose is, for example ColumnsCalloutHandler.js.

Note that you can have multiple callout handlers, each one performing different types of callout functions, for example, ColumnsCalloutHandler.js, FiltersCalloutHandler.js, etc.

If you have multiple callout handlers, they all need to be specified in the application’s config.xml file; see step 5.
Open the callout handler file in the ...\JSXAPPS\Callouts\ directory and modify it for the callouts you want to implement, as follows:
1. Locate the registerHandler function and ensure that the callout methods you are implementing are uncommented. Note that some of the methods are uncommented by default. Comment those out if you are not implementing those methods.
2. Locate the method(s) you want to implement and modify them as follows:
  - All of the callout methods have two parameters: oValue and oContext (the lone exception is the modifyMatrix method, which has oMatrix and oContext parameters):
    oValue - An object with properties that are determined by the type of callout. The properties of this object are modified as required by the callout and returned as output of the method.
    
    oContext - This object provides information about the list being modified, as well as information about the logged-in user. This includes properties such as oContext.userName (name of the logged-in user) and oContext.userGuid (unique identifier of the logged-in user). It may include additional properties, depending on the type of callout.
  - Each callout method has a SAMPLE CHANGE example that illustrates making a modification to a filter, sort, column, etc., for a particular list type.
  - Each of the callout methods contains if/else statements that provide a location to place code that modifies the oValue object for each of the list types for which the method applies.
  - You can easily enable or disable the method for each list type by either commenting (to enable) or uncommenting (to disable) the oValue = null: line in the appropriate if/else segment for the desired list type.
3. Save and close the callout handler file.
Open and update your WCC application’s config.xml file as described below.¹ This file is located as follows:
```
StudioHome\wcc\version\JSXAPPS\WCCProjectName\config.xml
```
where:
- StudioHome is the directory in which TIBCO Business Studio was installed.
- version is the version number of Workspace that was installed with TIBCO Business Studio.
- WCCProjectName is the name of the General Interface Builder project that contains your WCC application. If you are working with the Workspace application, this is “workspace”.
1. Locate the <record jsxid="customCallout"> element and specify a <Class> element for each callout handler to implement. This must include the fully qualified name of the callout handler. For example, if your WCC application is named “accounts”, it must appear as follows:
```
<record jsxid="customCallout" type="Workspace">
   <Classes>
      <Class class="com.tibco.wcc.accounts.CalloutHandler" />
   </Classes>
</record>
```
  Note that the <Classes> element can contain multiple <Class> elements if you have created multiple callout handlers to handle different types of callouts (for example, ColumnsCalloutHandler.js, FiltersCalloutHandler.js, etc.).
2. Locate and uncomment the example mapping record for the callout handler:
```

```
3. In the mapping record that you have uncommented, ensure that the id and src records match the name and location of your callout handler.
4. If needed, modify the value of the jsxid attribute in the top-level record (the one in which type=”map”). By default, the value is:
```
jsxid="com.tibce.wcc.workspace.CalloutHandler"
```
  Note that the value of this attribute must match the class name for the callout handler in the customCallout record (see step 5a above).
  
  Therefore, if you are using the Workspace application, the default value of the jsxid attribute in the top-level record may be fine (assuming your callout handler is called “CalloutHandler”).
  
  If, however, you are configuring a custom WCC application, you will need to modify the value of the jsxid attribute to include the name of your WCC application. For example, if the name of your WCC application is “accounts”, the value of the jsxid attribute may need to be changed to:
  
  jsxid="com.tibce.wcc.accounts.CalloutHandler"
  
  Again, this assumes the name of your callout handler is “CalloutHandler”. If it is something like “ColumnsCalloutHandler”, include that in the value.
5. If you are configuring multiple callout handlers (for example, FilterCalloutHandler and SortCalloutHandler), copy and paste the mapping record that you uncomment in step 5b above, and modify its contents according to the instructions in steps 5c and 5d.
  For example, if you have two callout handlers, FilterCalloutHandler and SortCalloutHandler, you need two mapping records (as well as two class elements in the customCallout record; see step 5a above):
```
<record jsxid="com.tibco.wcc.workspace.FilterCalloutHandler" type="map">
  <record jsxid="id" type="string">FilterCalloutHandler</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/Callouts/FilterCalloutHandler.js</record>
</record>

<record jsxid="com.tibco.wcc.workspace.SortCalloutHandler" type="map">
  <record jsxid="id" type="string">SortCalloutHandler</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/Callouts/SortCalloutHandler.js</record>
</record>
```
6. Save and close the config.xml
  
  Note: If you configure multiple callout handlers, and they implement the same callout method, only the method in the last handler that is loaded is executed.
Optionally modify user access profiles that are to be used on conjunction with the callouts. For example, if your custom handler is setting the default columns on the work item list, you may want to deny access to "SelectColumns" for the work item list in your application’s userAccess.xml file. For information about setting user access profiles, see the TIBCO Workspace Customization and Configuration guide.
If you are implementing callouts in a custom WCC application, you will need to deploy the application to a node after you are finished customizing it. For information, see the "Deploying an Application After Customizing" topic in the TIBCO Workspace Customization and Configuration guide.

¹ If you are configuring custom callout handlers for a deployed, running application, you can use the Configuration Administrator to update the application’s configuration file, rather than opening and updating the file (config.xml) directly. For information, see Using Configuration Administrator to Configure Callout Handlers.

Contents

Index

Search Results

Callout Handler Configuration

Procedure