Dispatchers and Services

The dispatcher is the entry point for IBM Cognos 8 service requests sent by a Web server gateway or other software. The dispatcher handles the routing requests and balances the load of user requests to the various IBM Cognos 8 services.

You can have more than one dispatcher in your IBM Cognos 8 environment. In such distributed installations one dispatcher is configured for every instance of the Content Manager or Application Tier Components that are installed and configured in your environment.

After you install and configure IBM Cognos 8, one dispatcher is available on each computer by default. Each dispatcher has a set of associated services, listed in the following table.

IBM Cognos 8 Services

After you install and configure IBM Cognos 8, one dispatcher is available on each computer by default. Each dispatcher has a set of associated services, listed in the following table.

You can perform the following maintenance on dispatchers and their associated services:

• start and stop dispatchers and services
• activate a Content Manager service

• remove dispatchers from the environment

• group dispatchers in configuration folders
• specify advanced dispatcher routing
• specify gateway mappings
• rename dispatchers
• test dispatchers
• administer failover for multiple dispatchers

Stop and Start Dispatchers and Services

You can stop and start dispatchers and services manually. If a service stops responding, you must stop and restart it.

Each dispatcher and service can be

• started

• stopped immediately and delete all the requests that are running or queued, without completing those requests

• stopped after running and queued requests are processed

You can stop or start all dispatchers and services in the IBM Cognos 8 environment at once.

When you start IBM Cognos 8 using the configuration tool, all dispatchers and services start unless they are disabled in the configuration tool. For more information, see the Installation and Configuration Guide.

By default, all services start when you restart the computer on which they are installed.

Stopping a service also stops all its processes. When you stop a dispatcher, all its services are stopped. If the suspended dispatcher has an active Content Manager, all users except administrators are locked out.

After a service is stopped, it has a suspended status System Performance Metrics.

You must have the required permissions to access IBM Cognos Administration functionality. See Secured Functions and Features.

Steps

1. Start IBM Cognos Connection.

2. In the upper-right corner, click Launch, IBM Cognos Administration.

3. On the Status tab, click System.

4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu and find the dispatchers or services that you want.

   Click All servers, All server groups, or All dispatchers. To select a service, pause your pointer over Services and click the required service.

5. Click the arrow next to the dispatcher or service, and choose the action that you want to perform.

   Depending on the dispatcher or service, you can do the following:

   Goal	Action
   Start all dispatchers in system	With all servers displayed, in the upper right corner of the Scorecard pane, click the arrow to view the Toolbar actions menu, and then click Start dispatchers. Tip: To apply a toolbar action to only some entries, select check boxes for one or more entries and then click the toolbar action that you want.
   Start all dispatchers for a server group	With all server groups displayed, click the arrow to view the Actions menu next to the server group, and then click Start dispatchers.
   Start all dispatchers for a server	With all servers displayed, click the arrow to view the actions menu next to the server, and then click Start dispatchers.
   Start a specific dispatcher	With all dispatchers displayed, click the arrow to view the Actions menu next to the dispatcher, and then click Start.
   Start a specific service	With all services displayed, click the arrow to view the Actions menu next to the service, and then click Start.
   Stop all dispatchers in system	With all servers displayed, in the upper right corner of the Scorecard pane, click the arrow to view the Toolbar actions menu, and then click Stop dispatchers immediately or Stop dispatchers after running and queue processed.
   Stop all dispatchers for a server group	With all server groups displayed, click the arrow to view the Actions menu next to the server group, and then click Stop dispatchers immediately or Stop dispatchers after running and queue processed.
   Stop all dispatchers for a server	With all servers displayed, click the arrow to view the Actions menu next to the server, and then click Stop dispatchers immediately or Stop dispatchers after running and queue processed.
   Stop a specific dispatcher	With all dispatchers displayed, click the arrow to view the Actions menu next to the dispatcher, and then click Stop immediately or Stop after running and queue processed.
   Stop a specific service	With all services displayed, click the arrow to view the Actions menu next to the service, and then click Stop immediately or Stop after running and queue processed.

   A dialog box appears and confirms the action.

6. Click Close.

Activate a Content Manager Service

One Content Manager service is designated to become active at startup. All other Content Manager services start up in standby mode. Only one Content Manager service can be active at any time.

You can manually activate a Content Manager service that is in standby mode. When you activate a service, any currently active service switches to standby mode.

You can also specify a Content Manager service which is currently standby as the default active service at startup.

You must have the required permissions to access IBM Cognos Administration. See Secured Functions and Features.

Steps to Specify a Default Content Manager Service

1. Start IBM Cognos Connection.

2. In the upper-right corner, click Launch, IBM Cognos Administration.

3. On the Status tab, click System.

4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu. Click Services, and then click Content Manager.

5. Click the arrow for the Actions menu next to the Content Manager service and click Set as active by default.

   Tip: Only Content Manager services that are not already the default have Set as active by default displayed in the Actions menu.

Steps to Activate a Content Manager Service

1. Start IBM Cognos Connection.

2. In the upper-right corner, click Launch, IBM Cognos Administration.

3. On the Status tab, click System.

4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu. Under Services, click Content Manager

5. C lick the arrow to view the Actions menu next to the Content Manager service, and then click Start.

Remove Dispatchers from the Environment

You can remove a dispatcher if you no longer need it in the IBM Cognos 8 environment. To remove a dispatcher, you must first uninstall the dispatcher from the computer where it is installed. You must then unregister it to remove it from the content store.

You must have the required permissions to access IBM Cognos Administration functionality. See Secured Functions and Features.

Steps

1. Start IBM Cognos Connection.

2. In the upper-right corner, click Launch, IBM Cognos Administration.

3. Click the Status tab, and then click System.

4. Determine the dispatchers that you want to unregister.

5. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu. Click All servers, All server groups, or All dispatchers.

   Goal	Action
   Unregister all dispatchers in system	With all dispatchers displayed, in the upper-right corner of the Scorecard pane, click the arrow to view the Toolbar actions menu, and then click Unregister dispatchers. Tip: To apply a toolbar action to only some entries, select check boxes for one or more entries and then click the toolbar action that you want.
   Unregister all dispatchers for a server	With all servers displayed, click the arrow next to a server to view the Actions menu, and then click Unregister dispatchers.
   Unregister all dispatchers for a server group	With all server groups displayed, click the arrow next to a dispatcher to view the Actions menu, and then click Unregister dispatchers.
   Unregister a specific dispatcher	With all dispatchers displayed, click the arrow next to a dispatcher to view the Actions menu, and then click Unregister.

   A dialog box appears to confirms the action.

6. Click OK.

   The dispatcher information is removed from the content store. You can now uninstall it. If you do not uninstall the dispatcher, it reregisters itself and restarts the next time that IBM Cognos 8 is restarted. For information about uninstalling, see the Installation and Configuration Guide.

Group Dispatchers in Configuration Folders

Configuration folders are useful to organize dispatchers if your installation includes many dispatchers. You can group dispatchers so that you can apply the same configuration settings once to all the dispatchers and services in the folder.

When you add a dispatcher to a configuration folder, it automatically inherits the configuration settings of the folder. However, if you previously changed the default values of that dispatcher or service, the changed values are kept.

When you change the configuration settings of a dispatcher or configuration folder, the services for the dispatcher and any child entries for the folder automatically acquire the new values. However, if you change the values of the services, the changed values are kept.

You can create a new configuration folder at the root of the Configuration area or in an existing configuration folder.

Tips

• To view and edit the configuration properties of the parent of an entry shown in the path on the toolbar, click the set properties button . You can change and apply configuration settings for all the dispatchers and services in the Configuration area when you are in the root of the Configuration area.

• Use the path on the toolbar to explore the different levels of your configuration. The path starts with Configuration and, when the path becomes too long, it wraps.

You must have the required permissions to access IBM Cognos Administration functionality. See Secured Functions and Features.

Steps

1. Start IBM Cognos Connection.

2. In the upper-right corner, click Launch, IBM Cognos Administration.

3. On the Configuration tab, click Dispatchers and Services.

4. Click the new folder button.

5. Type a name and, if you want, a description, and specify where to save the configuration folder.

6. Click Finish.

   You can now add dispatchers to the configuration folder by cutting them from their original location and then pasting them inside the folder. You can also change settings at the configuration folder level.

   Tip: To move a dispatcher to another folder, click More next to the dispatcher and then click Move.

Specify Advanced Dispatcher Routing

Depending on how your system is set up, you may want to control how reports are distributed among servers. For example, you have different departments that maintain their own servers, or you have specific servers set up for specific data access, such as Windows servers for Microsoft SQL Server databases and Linux servers set up for DB2 access. You can set up IBM Cognos 8 so that report requests are processed by specific servers by applying routing rules.

Affinity settings take precedence over advanced routing settings.

Server Groups

When you define the routing rules, you must select a server group. Server group names are a property of a dispatcher or the configuration folders into which the dispatchers are organized. See to set server group names.

To determine which server groups process certain reports, you must associate keywords with packages and user roles or groups, and then specify how the keywords are distributed among the dispatchers in your environment. The distribution is controlled by routing rules that you create for the routing keywords. The report request will be processed by a specific server depending on the keywords associated with the package from which the report was created and/or the user or group running the report.

When you create the routing rules, you create conditions that determine the server groups by which the reports are to be processed. For example, you can set up routing rules so that reports from a Finance package made by a user in the Finance group are processed by Finance servers. Alternatively, you can set up routing rules so that reports by any Sales users, regardless of which package was used to create the report, are processed by Sales servers. In the first example, you would specify keywords for both user role or group and package, but in the second you would only specify a keyword for user role or group and leave the package keyword blank. You do not have to specify a keyword for both package and user role or group in your routing rules.

You set up the routing keywords and the routing rules using IBM Cognos Connection.

You must have the required permissions to access IBM Cognos Administration functionality. See Secured Functions and Features.

Steps to Set Routing Keywords for Packages

1. In IBM Cognos Connection, click the Public Folders tab.

2. Click the set properties button  for a package.

3. Under Advanced routing, click Set.

   The Assign routing sets page appears.

4. Type a routing keyword for the package in Type routing sets, and click Add.

5. Repeat step 4 to add other routing keywords that you want to apply to the package. Separate each keyword with a semi-colon, for example, Red;Blue;Green;

   The order in which the routing keywords are added does not matter.

6. Click OK.

   The routing keywords are displayed under Advanced routing.

7. On the Set properties page, click OK.

Steps to Set Routing Keywords for User Roles or Groups

1. Start IBM Cognos Connection.

2. In the upper-right corner, click Launch, IBM Cognos Administration.

3. Click the Security tab, and then click Users, Groups, and Roles.

4. Click the namespace to display the roles.

5. Click the set properties button  for a role or group.

6. Under Advanced routing, click Set.

   The Assign routing sets page appears.

7. Select a routing keyword for the users role or group in Select routing sets, or type it in Type Routing Sets, and click Add. If you are typing, separate each keyword with a semi-colon, for example, Red;Blue;Green;.

8. Repeat step 7 to add other routing keywords that you want to apply to the users role or group.

   The order in which the routing keywords are added does not matter.

9. Click OK.

   The routing keywords are displayed under Advanced routing.

10. On the Set properties page, click OK.

Steps to Set Routing Keywords for Server Groups

1. Start IBM Cognos Connection.

2. In the upper-right corner, click Launch, IBM Cognos Administration.

3. On the Configuration tab, click Dispatchers and Services.

   The dispatchers and any configuration folders that have been created are shown.

   Note: You can only apply routing rules to server groups. Server groups are a property of dispatchers or configuration folders, and must be set up before you can set routing keywords for server groups .

4. Click the specify routing rules button .

   The Specify the routing rules page appears.

5. Click Add a rule.

6. Select the Package routing set, Group routing set, Role routing set, and Server group that you want.

7. In the Actions column, click the View the members button to see an overview of the members.

8. To change the order of routing rules, click Modify the sequence, and then the item you want to move and click Up, Down, To top, or To bottom.

   Note: Unlike routing keywords, the order in which the routing rules are listed affects how they are applied. A rule is matched when properties associated with the package and/or the user or group involved in the request satisfy the criteria of the rule. The rules are evaluated in order until the first one is matched, and the request is routed to the server group named by the first rule that was matched. You can change the order of the rules by clicking Modify the sequence.

9. Click OK.

Specify Gateway Mappings for Series 7 PowerPlay Data

IBM Cognos 8 Go! Office users may send requests to Report data service (RDS) for data that resides on a Series 7 PowerPlay server. Report data service (running on the IBM Cognos 8 application server) communicates with Series 7 PowerPlay through the Series 7 PowerPlay Enterprise Server gateway.

If the network configuration prohibits application server access to the Web tier server that hosts the Series 7 PowerPlay Enterprise Server gateway, then a second internal Series 7 PowerPlay Enterprise Server gateway must be installed in the application server tier. In this type of configuration, you can specify the location of the Series 7 PowerPlay server by using the Gateway Mappings setting in Server Administration.

Steps

1. Start IBM Cognos Connection.

2. In the upper-right corner, click Launch, IBM Cognos Administration.

3. On the Status tab, click System.

4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu. Click Services, and then click Report data.

5. Click the arrow next to reportDataService to view the Actions menu, and then click Set properties.

6. Click the Settings tab.

7. In the Value column, click Edit for Gateway mappings.

8. Click the check box Override the settings acquired from the parent entry.

9. Click Add a mapping.

10. For Application gateway (external), type the address of the Web server.

11. For Application gateway (internal), type the address of the Series 7 PowerPlay server.

12. Click OK.

Rename Dispatchers

As a security measure, you can rename dispatchers if you do not want to reveal the host computer name, port number, servlet, or path of the dispatcher .

Typically, server administrators can view and change the name of dispatchers.

We recommend that when renaming a dispatcher, you do not use any information that reveals the host computer name or port, or other system or path information. However, it is important to remember where the dispatcher is installed, for monitoring purposes.

Tip: If you rename a dispatcher and need to access the host, port, and path information, you can use the SDK methods to find this information in the dispatcherPath property of the Dispatcher Object.

You must have the required permissions to access IBM Cognos Administration functionality. See Secured Functions and Features.

Steps

1. Start IBM Cognos Connection.

2. In the upper-right corner, click Launch, IBM Cognos Administration.

3. On the Status tab, click System.

4. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu. Click All dispatchers.

5. Click the arrow next to the dispatcher to view the Actions menu, and then click Set properties.

6. In the Name box, type the new name for the dispatcher.

   Use a meaningful name to help you distinguish dispatchers. Do not reveal system information in the name.

7. If you want, add a screen tip and description information.

8. Click OK.

Test Dispatchers

To evaluate how IBM Cognos 8 is performing, you can test the status of dispatchers. You can also ensure that the dispatchers are responding and view the uptime, which is the time in seconds during which the dispatchers are working without failure.

You can also view the status of dispatchers and service and review log messages.

When you test a dispatcher, you also test the services that belong to that dispatcher.

You must have the required permissions to access IBM Cognos Administration.

Steps

1. Start IBM Cognos Connection.

2. In the upper-right corner, click Launch, IBM Cognos Administration.

3. On the Status tab, click System.

4. Determine the dispatchers that you want to test then follow the instructions in this table. In the upper-left corner of the Scorecard pane, click the arrow to view the Change view menu and then click the items you want to display.

   Goal	Action
   Test all dispatchers in system	With all servers displayed, in the upper right corner of the Scorecard pane, click the arrow to view the Toolbar actions menu, and then click Test. Tip: To apply a toolbar action to only some entries, select check boxes for one or more entries and then click the toolbar action that you want.
   Test all dispatchers for a server group	With all server groups displayed, in the upper right corner of the Scorecard pane, click the arrow to view the Toolbar actions menu, and then click Test dispatchers.
   Test all dispatchers for a server	With all servers displayed, click the arrow next to the server to view the Actions menu, and then click Test.
   Test a specific dispatcher	With all dispatchers displayed, click the arrow next to the dispatcher to view the Actions menu, and then click Test.

   A dialog box appears and confirms the action.

5. Click OK.

   If dispatchers are not performing as they should, you can tune server performance by changing their configuration settings .

Administering Failover for Multiple Dispatchers

In a distributed IBM Cognos 8 installation, you may choose to configure each of your gateway components to communicate with more than one dispatcher for failover purposes. The gateway components scan their associated dispatchers to ensure that requests are routed to dispatchers that are in service and responding correctly. You can set the frequency with which these scans are executed.

For information about configuring multiple dispatcher, see the "Configuring Gateway Computers" topic in the Installation and Configuration Guide.

Set the Frequency of Dispatcher Status Scans

You can specify how often dispatchers are scanned to determine their current status for failover purposes.

Steps

1. Copy the c8_location/cgi-bin/cognoscgi.conf.sample file to c8_location/bin and rename it cognoscgi.conf.

2. Open the cognoscgi.conf file in an editor that can save files in UTF-8 format.

3. Add the following lines to the file:

   ConnectionCheckingSleepTime=time in seconds

   ConnectionCheckingQuickSleepTime=time in seconds

4. Save the cognoscgi.conf file in UTF-8 format.

Set the Frequency of Dispatcher Scans for a Servlet Gateway

If you have chosen to use Servlet Gateways, you can specify how often they scan dispatchers for their current status. Traffic is routed to another dispatcher if the first one fails.

For information about gateways and URIs, see the Installation and Configuration Guide.

Steps

1. Open the Servlet Gateway web.xml file, located either in c8_location/war/gateway/ or in the deployment directory of the servlet, depending on which server you are using, in an editor that supports saving files in UTF-8 format.

2. Change the values for the parameters as required.

   <!-- The number of seconds between pings to dispatcher
   --> 
   			<param-name>pingPeriod</param-name> 
   			<!-- A non-zero positive integer --> 
   			<param-value>180</param-value> 
   		</init-param> 
   		<init-param> 
   			<!-- The number of seconds between checking the startup file
   for changed dispatchers --> 
   			<param-name>fileCheckPeriod</param-name> 
   			<!-- A non-zero positive integer --> 
     			<param-value>30</param-value> 
       		</init-param>

3. Save the web.xml file in UTF-8 format.

Securing Dispatchers

Users of IBM Cognos 8 can enter XPath search paths in the address field of a Web browser, or in hyperlinks. The users can input any search path syntax against search path parameters in the user interface. IBM Cognos 8 relies on the Content Manager Access Control List to check the objects that are returned to the user.

In some cases, malicious users could see the dispatcher name in IBM Cognos Connection by providing a crafted search path. This can pose a security risk, even though the users cannot click the object or perform any actions on the object.

To avoid this type of security risk, administrators can:

• set the advanced parameter CM.SECURITYQUERYREQUIRESREAD to TRUE.

  For more information, see Set Advanced Content Manager Parameters.

• change the default dispatcher name

  The default dispatcher name is computer_name:9300 and it can be changed to, for example, server1 to mask the port number and host name.

  For more information, see Rename Dispatchers.

For more information about other security technics used in IBM Cognos Connection, see the Architecture and Deployment Guide.