Working with failed events

You can use two tools in IBM WebSphere InterChange Server Express to locate, view, and process failed events: Failed Event Manager, a browser-based tool with role-based security that allows you to work with failed events from the Web, and Flow Manager, a tool installed with the InterChange Server Express product. To resolve transactional flows, you must use Flow Manager, but both Failed Event Manager and Flow Manager allow you to work with failed events. This section contains the following:

Using Failed Event Manager

Using Flow Manager

Using Failed Event Manager

Failed Event Manager allows you to view and manage failed events from the Web. The actions you can perform with those failed events depends on role-based security. Administrators can assign users one or more of four default roles:

Administrators also can create custom roles for your specific team using Application Assembly Tool.

Failed Event Manager works with IBM WebSphere Application Server or with Tomcat (Windows and Linux systems only). Refer to the WebSphere Business Integration Server Express installation guide for Windows, for Linux, or for OS/400, for additional information about setting up Failed Event Manager to work with WebSphere Application Server, WebSphere Application Server Express, or Tomcat. OS/400 does not support Tomcat.

Failed Event Manager works with the following versions of WebSphere Application Server, WebSphere Application Server Express, and Tomcat:

This section includes the following procedures:

Setting up security for Failed Event Manager

Administrators must set up security for using Failed Event Manager with WebSphere Application Server. In addition, administrators can create additional security roles if your team wants to use more than just the four default user roles. There are different ways to create those roles depending on whether you are using WebSphere Application Server or Tomcat with Failed Event Manager.

Steps for setting up security for Failed Event Manager and WebSphere Application Server

If you your group uses Tomcat with Failed Event Manager, there are no additional steps to enable the default role-based security. If you use WebSphere Application Server, the administrator must enable security.

Perform the following steps to enable role-based security for Failed Event Manager with WebSphere Application Server:

  1. Start WebSphere Application Server by doing the following:
  2. On the left navigation frame, click Security > User Registries > Local OS.
  3. On the Local user registry page type a valid local OS user name and password and click OK.

    The Global Security page appears.

  4. Under General Properties, select the Enabled check box.
  5. Make sure the Enforce Java2 security check box is cleared, leave other default values unchanged, and click OK.
  6. Click the Save button on the message about changes to local configuration. The Save page appears.
  7. Under Save To Master configuration, click Save.
  8. Restart WebSphere Application Server (see step 1).
  9. Open the Administrative Console. If security has been configured correctly, the console page asks for a user name and password (These are the values you you typed on the Local user registry page in step 3), and click OK.

    The main Administrative Console page appears.

  10. Do the following to install the Failed Events Manager application on the WebSphere Application Server (if not already installed)
  11. Restart WebSphere Application Server.

Steps for creating custom roles for Failed Event Manager with WebSphere Application Server Express

WebSphere Application Server Express includes a tool called Studio Site Developer that administrators use to edit a WAR file and create customized roles. Studio Site Developer is included on the second WebSphere Application Server CD; you install it from there. For details on installing WebSphere Studio Site Developer tools, see the WebSphere Business Integration Server Express installation guide for Windows, for Linux, or for OS/400.

Perform the following steps to create custom roles if you are using WebSphere Application Server Express:

  1. Start the Studio Site Developer by clicking Start > Programs > IBM WebSphere Application Server Express 5.1.1 > Studio Site Developer.
  2. Open the Web perspective. After the workbench comes up, click Window > Open Perspective > Web.
  3. Import the FailedEvents.war file to be edited by clicking File > Import, selecting the file and clicking Next.
    OS/400

    For OS/400, the war file is loaded on the OS/400, not on Windows. So you must either copy it to Windows or map a drive to the OS/400 from Windows. The file on OS/400 is /qibm/proddata/wbiserver43/product/WBFEM/WAS/FailedEvents.war.


    Do not edit the file in proddata. Copy it to another path on OS/400, edit it there, and then deploy the changed war file from the new location.

  4. Click the browse button to select the FailedEvents.war file to be edited.
  5. Create a web project by doing the following:
  6. Expand the FailedEventWebProject and double-click the Web Deployment Descriptor. A tabbed window opens in the editor, with the Overview tab displayed by default.
  7. Create custom roles by doing the following:
  8. Click the Security Constraints tab on the Security screen and add the new roles to the security constraints by doing the following:
  9. Click the Servlets tab at the bottom of the editor screen and edit the initialization parameters of the Login servlet to describe each role you created:
  10. Click File > Save to save the project in Studio Site Developer.
  11. Export the project to a WAR file by right-clicking the web project in the Project Navigator view and clicking Export:

Steps for creating custom roles for Failed Event Manager with WebSphere Application Server

WebSphere Application Server includes a tool called Application Assembly Tool that administrators use to edit a WAR file and create customized roles. (For OS/400, administrators use the tool on Windows to edit the jar file that is stored and deployed on OS/400.)

Perform the following steps to create custom roles if you are using WebSphere Application Server:

  1. Start the Application Assembly Tool by selecting Start > Programs > IBM WebSphere Application Server > Application assembly tool.
  2. In the Welcome dialog box, click on the Existing tab and browse to select the FailedEvents.war file. Click OK.

    The complete structure of the war file appears in the left pane.

  3. Right click Security Roles and click New.
  4. In the New Security Role dialog box, type a name and description for the new role, and click OK.
  5. Expand Security Constraints and select SC1 from the left pane.
  6. On the right pane, under Authorization Constraints click Add.
  7. Select the role you created and click OK.
  8. Click Apply.
  9. From the root on the left pane, expand Web Components -> expand Login -> right click on Initialization parameters.
  10. Select the Role Components parameter and edit the parameter value.

    The parameter value is a string in the following format:

    <RoleName1>:event_owners=<ownername>*connectors=<connectorName>*bos=
    

    <boname.verb>#
    

    <CompositeKeyValue>+<CompositekeyValue2>/<AnotherPossibleKeyValue>  |
    

     <RoleName2>: 
    

    ......
    

    < | > - separates two roles

    < : > - separates role name from components of the role

    < * > - separates components (connectors and business objects) within a role

    < = > - separates component name from its values

    < , > - separates values within a component

    < # >- separates business object name from its key values

    < / > - separates possible keys of a business object (same business object - different key)

    < + > - separates composite keys of a business object (make sure these key values are provided in the particular order in which they appear in the business object)

    For example:

    Role1:event_owners=collab1, collab2*connectors=conn1,
    conn2*bos=bo1.create#55/67, 
    

    bo2.delete#99/80
    

     |Role2:event_owners=collab3,collab4*connectors=conn3*bos=bo4.create
    #59+9876/82, bo2.delete#56
    

    In this example, "event_owners" refers to point of failure of the event, either at a collaboration or at a connector.

  11. After typing the parameter value, click Apply.
  12. Click File > Save. The war file is ready to be deployed.
  13. After you have created these roles, you must set up security again. Go to Steps for setting up security for Failed Event Manager and WebSphere Application Server.

Steps for creating custom users and roles for Failed Event Manager with Tomcat

This section applies to Windows and Linux systems only. OS/400 does not support Tomcat.

Perform the following steps to create custom users and roles if you are using Tomcat:

  1. Edit the tomat-users.xml file located under Tomcat_Home\conf to make the following changes as needed:
  2. Save the file.
  3. Edit the web.xml file located under Tomcat_Home\webapps\FailedEvents\WEB-INF to add the roles you added to the tomat-users.xml file in step 1. Do the following:
  4. Save the file.
  5. Start Tomcat from the command line in order to call the setclasspath.bat file: Tomcat_home/bin/startup.bat.

Steps for logging on to Failed Event Manager

Failed Event Manager can only be accessed through a supported browser on Windows platforms only. The supported browsers are:

Perform the following steps to log on to Failed Event Manager:

  1. Open the browser on Windows and type one of the following URLs, depending on how Failed Event Manager was set up for your team:
  2. If security is enabled, you must type the Application Server user name and password.
  3. At the Connect screen, type the Server Name, User Name and Password, and click Login.

    Figure 61. Failed Event Manager Connect screen


    After you log on, the Query dialog box appears, as shown in Figure 62.

    Figure 62. Failed Event Manager Query dialog box


Steps for viewing failed events

Perform the following steps to view information about failed events in Failed Event Manager:

  1. On the Query page, select the information about the failed events that you want to view:
  2. Click Submit.

    A Table of Failed Events appears, as show in Figure 63.

    Figure 63. Failed Event Manager Table of Failed Events


    If you are not assigned to one of the roles that has access to viewing business objects, the business object buttons may not be available in this table, as shown in Figure 64.

    Note:
    Depending on your browser, buttons or other controls either do not appear or appear and are unavailable.

    Figure 64. Failed Event Manager Table of Failed Events without rights to view business objects


  3. If you want to view details for a particular failed event, select the check box in the left column and click View in the Details column.

    The Event Details dialog box appears, as shown in Figure 65.

    Figure 65. Failed Event Manager Event Details dialog box


  4. If you are assigned to a role that has access to the business object, click the business object button in the Business Objects column to view details about the business object. The Business Object Data dialog box appears, as shown in Figure 66.

    Figure 66. Failed Event Manager Business Object Data dialog box


Steps for processing failed events in Failed Event Manager

Perform the following steps in a Table of Failed Events to process failed events:

  1. Select the check box in the left column for the failed events that you want to work with.
  2. Do one of the following:

Steps for checking your access rights in Failed Event Manager

Perform the following steps to check the roles you are assigned for Failed Event Manager role-base security:

  1. log on to Failed Event Manager (see Steps for logging on to Failed Event Manager).
  2. On the query page that opens, click the Check your access rights link in the bottom left.

    A page appears listing the default roles available. You can type a role name to see if you are assigned to that role.

Using Flow Manager

To locate, view, and process failed events, use Flow Manager, a tool that is installed with the InterChange Server Express product. Flow Manager allows you to easily construct a query to locate and display unresolved flows. After you display the unresolved flows, you can select any flow in the display and submit it, discard it, or perform other actions. For background information on failed flows, see Flow failures.

The following topics describe how to use Flow Manager for constructing the queries, viewing the details, and processing the events:

Steps for starting Flow Manager

Steps for finding unresolved flows

"Steps for viewing details for unresolved flows"

Steps for processing unresolved flows

Steps for starting Flow Manager

Perform the following steps to start Flow Manager:

  1. Click Start > Programs > IBM WebSphere Business Integration Express > Toolset Express > Administrative > Flow Manager. The Connect to InterChange Server dialog box appears (see Figure 67.

    Figure 67. Connect to InterChange Server dialog box


  2. Enter the server name, using any one of the following methods:
  3. Type the user name and password for the server you want to connect to. If you check the Remember user name and password check box, the user name and password are stored in the registry along with the server name, and the password are encrypted. Click Connect.
    Note:
    To remove unwanted users or servers from the registry, click Options. This opens the Options dialog box, from which you can remove servers or users.
    The following figure shows the Options dialog box.

    Figure 69. Options dialog box


After you click Connect in the Connect to InterChange Server dialog box, Flow Manager opens (see Figure 70).

Figure 70. Flow Manager


Steps for finding unresolved flows

Perform the following steps in Flow Manager to find all unresolved flows:

  1. Start Flow Manager. See Steps for starting Flow Manager.
  2. Do one of the following:
  3. After specifying your search criteria, click the Find button or click Event > Find. The results appear in the bottom half of the Flow Manager window (see Figure 71).

    Figure 71. Flow Manager displaying filtered results


  4. To save the current filter information as a query, click Query > Save. The query name you type appears in the Query list.

Event Attributes tab

Click the Event Attributes tab to search according to the characteristics of the unresolved event (see Figure 72).

Figure 72. Flow Manager Event Attributes tab


The following options are available from the Event Attributes tab:

Date & Time tab

Use the Date & Time tab to query only the flows that failed during a specific time period (see Figure 73).

Figure 73. Date & Time tab


The following options are available from the Date & Time tab:

Error Text & Business Object Attributes tab

Use the Error Text & Business Object Attributes tab to construct a query that includes only certain business objects, business object attributes, and attribute values (see Figure 74).

Figure 74. Error Text & Business Object Attributes tab


Select values in the following columns:

You can also query only unresolved flows that produce a message containing specified text that you type in the Containing Error Text field.

Note:
The keywords you type in the Containing Error Text field are not case-sensitive.

Steps for viewing details for unresolved flows

Perform the following steps to view details for unresolved flows in Flow Manager:

  1. Select a query from the Query list.
  2. Do one of the following:

    The results appear in the bottom half of the Flow Manager window (see Figure 71).

    An unresolved flows table appears with a list of events and the following information:

    For the waiting events, the Event Status cell contains the following information:


    Waiting
    [timeout expiration:...]
    [scenario name:...]
    [scenario node ID...]

  3. To access more information about any of the events, double-click the row containing the event (or click Event > Select All). This opens the Show Event Details dialog box (see Figure 75).

    Figure 75. Flow Manager Show Event Details dialog box


  4. To access more information about the business object associated with the selected event, click Event > Display Details. The Show Business Object Data dialog box appears (see Figure 76).

    Figure 76. Show Business Object Data dialog box


If you want to take action on any of the unresolved flows, refer to Steps for processing unresolved flows.

Steps for managing queries

Perform one of the following steps to manage queries you created for unresolved flows:

Steps for managing results of queries

Perform the following steps to manage queries you created for unresolved flows:

  1. In the results list in Flow Manager, select one or more events in the results list.
  2. Do one of the following:

Steps for processing unresolved flows

Perform the following steps to process any failed events in the results list in Flow Manager:

  1. In the results list in Flow Manager, select one or more events in the results list.
  2. Do one of the following:

Copyright IBM Corp. 2004