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
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:
- Administrator -- rights to view and resubmit failed events.
- ViewAll -- rights to view events and business object data.
- ViewEvents -- rights to view events only, not business object data.
- SubmitEvents -- rights to resubmit and view events but not business object
data.
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:
- WebSphere Application Server versions 5.0.2 or 5.1
- WebSphere Application Server Express versions 5.0.2 or
5.1
If you selected an Administrative Toolset installation of WebSphere
Business Integration Server Express, Failed Event Monitor is automatically
installed and configured if WebSphere Application Server or WebSphere
Application Server Express versions 5.0.2 or 5.1 are
detected on your system. Only role-based security must be
configured. Refer to Setting up security for Failed Event Manager.
- Tomcat versions 4.1.24 and 4.1.27 (Windows and
Linux systems only)
By default, security is enabled after you have installed Tomcat with Failed
Event Manager (Refer to the WebSphere Business Integration Server Express
installation guide for Windows, for Linux, or for OS/400). A user with
the role of Administrator must be created in the
Tomcat_home\conf\tomcat-users.xml file so that
the administrator can gain full access to the application. For details
on how to create roles in Failed Event Manager, refer to Setting up security for Failed Event Manager.
This section includes the following procedures:
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.
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:
- Start WebSphere Application Server by doing the following:
- Start server1 by selecting Programs > IBM WebSphere Application
Server v5.0 > Start Application Server on the Start
menu. Wait for the message "Server server1 open for e-business"
to appear before proceeding.
- On the Start menu, select Programs > IBM WebSphere Application
Server v5.0 > Administrative Console.
- Type your user ID and click OK.
OS/400 |
---|
For OS/400, perform the following steps to start WebSphere Application
Server:
- Enter CL command QSH and from the QSHELL environment, cd to the directory
/QIBM/Proddata/WebASE51/ASE/bin
for WebSphere Application Server Express,
or to the directory/QIBM/ProdData/WebAS51/Base/bin
for WebSphere Application Server.
Then run the following script:
startServer FailedEvents -instance FailedEvents.
- From a web browser go to:
http://HostName:9090/admin, where HostName
is the host name or host IP address.
|
- On the left navigation frame, click Security > User Registries
> Local OS.
- On the Local user registry page type a valid local OS user name and
password and click OK.
The Global Security page appears.
- Under General Properties, select the Enabled check
box.
- Make sure the Enforce Java2 security check box is cleared,
leave other default values unchanged, and click OK.
- Click the Save button on the message about changes to local
configuration. The Save page appears.
- Under Save To Master configuration, click
Save.
- Restart WebSphere Application Server (see step 1).
- 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.
- Do the following to install the Failed Events Manager application on the
WebSphere Application Server (if not already installed)
- Click Applications > Install New Application.
- Type the fully qualified path to the file named FailedEvents.war in
the WebSphereICS\WBFEM directory, or click the Browse button to navigate to
the file.
- Type FailedEvents in the Context Root field and
click Next.
- Accept the default values in the Preparing for the application
installation window and click Next.
- Click Next until you reach the Map security roles to users and
groups page. This shows the four default user roles and any additional
roles you created with the Application Assembly Tool.
- For each role, select the check box and click Lookup
users. Use the search string look for users locally or in the
domain, add the users and click OK.
- Click Next and then Finish.
- Click the Save to Master Configuration link when you see a
message that the application installed successfully.
- Click Save
- Restart WebSphere Application Server.
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:
- Start the Studio Site Developer by clicking Start > Programs >
IBM WebSphere Application Server Express 5.1.1 > Studio Site
Developer.
- Open the Web perspective. After the workbench comes up, click
Window > Open Perspective > Web.
- 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. |
- Click the browse button to select the FailedEvents.war file to be
edited.
- Create a web project by doing the following:
- Under Project, click New.
- On the next screen, type a name for the project,
FailedEventWebProject.
- Click Finish. On the project navigator view, a new web
project with the name you specified is listed.
- Expand the FailedEventWebProject and double-click the Web Deployment
Descriptor. A tabbed window opens in the editor, with the
Overview tab displayed by default.
- Create custom roles by doing the following:
- Click the Security tab at the bottom of the editor
screen.
- Click the Security Roles tab on the Security screen. The
default roles included with the WAR file are displayed.
- Click Add. Type in the name of the custom role you want
to create and enter a description for the role on the right hand side.
Repeat this for all the new roles that you want to create.
- Click the Security Constraints tab on the Security screen and
add the new roles to the security constraints by doing the following:
- Under Authorized Roles, click the Edit
button.
- In the Define Authorization Constraint dialog box, select the check box
next to the roles you created, and click OK.
- Click File > Save.
- 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:
- In the Servlets and JSPs list, select the Login
servlet.
- Under Initialization, enter the correct value for the ROLECOMPONENTS
parameter.
You can type in the value in a separate editor like notepad and paste it in
the value field.
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
- Click File > Save to save the project in Studio Site
Developer.
- Export the project to a WAR file by right-clicking the web project in the
Project Navigator view and clicking Export:
- Select WAR file and click Next.
- On the Export Resources to a WAR file screen, click the browse button
under Destination to either select a directory and type a new WAR
file name or to point to the WAR file you imported in step 4 if you want to
overwrite that file.
- Note:
- For OS/400, do not save the file in the ProdData directory. Copy it to
another path on OS/400, edit it there, and then deploy the changed war file
from the new location.
- Click Finish. The new WAR file is ready to be deployed
into WebSphere Application Server Express.
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:
- Start the Application Assembly Tool by selecting Start > Programs
> IBM WebSphere Application Server > Application assembly
tool.
- 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.
- Right click Security Roles and click New.
- In the New Security Role dialog box, type a name and description for the
new role, and click OK.
- Expand Security Constraints and select SC1 from the
left pane.
- On the right pane, under Authorization Constraints click
Add.
- Select the role you created and click OK.
- Click Apply.
- From the root on the left pane, expand Web Components -> expand Login
-> right click on Initialization parameters.
- 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.
- After typing the parameter value, click Apply.
- Click File > Save. The war file is ready to be
deployed.
- 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.
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:
- Edit the tomat-users.xml file located under
Tomcat_Home\conf to make the following changes as needed:
- To add a new role, for example, "Manager", add <role
rolename="Manager"/>.
- To create and assign a user, for example, Scott, to the role
"Manager" add <user username="Scott" password="tiger"
roles="Manager "/>
- You can assign more than one role to a user by separating the roles with
commas, for example: <user username="Scott" password="tiger"
roles="Manager, Employee"/>
- Save the file.
- 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:
- Add the custom roles to the following xml element, which already contains
the default roles:
<auth-constraint id="AuthConstraint_1062537631424">
<description>SC1:+:</description>
<role-name>Administrator</role-name>
<role-name>ViewEvents</role-name>
<role-name>ViewAll</role-name>
<role-name>SubmitEvents</role-name>
<role-name>Manager</role-name>
</auth-constraint>
- At the end of the xml file add a new element and assign a security role id
that is unique:
<security-role id="SecurityRole_1068513225089">
<description>Can manage all events.</description>
<role-name>Manager</role-name>
</security-role>
- Edit the init param value of the Login servlet as one complete
string:
<servlet id="Servlet_1062537018298">
<servlet-name>Login</servlet-name>
<display-name>Login</display-name>
<servlet-class>
com.ibm.btools.itools.FailedEvents.servlets.Login
</servlet-class>
<init-param id="InitParam_1063835207426">
<param-name>ROLECOMPONENTS</param-name>
<param-value>
role1: event_owners
SourceToDestCollab
|role2:event_owners=Collab2*
bos=CUSTOMER2.Create#2/4
|role3:event_owners=SourceToDestCollab, Collab2
</param-value>
<description>
Roles and components (collabs or connectors) associated with these roles.
</description>
</init-param>
</servlet>
The parameter value is a string in the following format:
<RoleName1>:event_owners=<ownername>*connectors=<connectorName>
*bos=<boname.verb> #<CompositeKeyValue>+<CompositekeyValue2>/
<AnotherPossibleKeyValue> | <RoleName2>: .....
Where:
< | > - separates two roles
< : > - separates the role name from components of the
role
< * > - separates components within a role, for example,
connectors and business objects
< = > - separates the component name from its values
< , > - separates values within a component
< # >- separates business object name from its key values
< / >- separates different possible keys of a business object
< + >- separates the composite key of a business object (two or more
primary keys)
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 the collaboration or at the connector.
- Save the file.
- Start Tomcat from the command line in order to call the
setclasspath.bat file:
Tomcat_home/bin/startup.bat.
Failed Event Manager can only be accessed through a supported browser on
Windows platforms only. The supported browsers are:
- Microsoft Internet Explorer 5.5 SP2 or higher, with Adobe SVG
Viewer 3.0 plug-in
- Netscape 4.7x (only), with Adobe SVG Viewer 3.0 plug-in
Perform the following steps to log on to Failed Event Manager:
- Open the browser on Windows and type one of the following URLs, depending
on how Failed Event Manager was set up for your team:
- If you are using WebSphere Application Server, type the URL:
http://HostName/FailedEvents
where HostName is the name of the computer on which WebSphere
Application Server is installed.
- You may have a port number as part of the URL. To access Failed
Event Manager, type the URL:
http://HostName:nnnn/FailedEvents
where HostName is the name of the computer on which WebSphere
Application Server is installed and nnnn is the port number.
- When Failed Event Manager is installed as part of WebSphere Application
Server Express, it is configured to use a default port number, 7089.
You can access Failed Event Manager with the following URL:
http://HostName:7089/FailedEvents.
- (Windows and Linux systems only) If you are using Failed Event Manager
with Tomcat, it is configured to use a default port number, 8080. You
can access Failed Event Manager with the following URL:
http://HostName:8080/FailedEvents.
- If security is enabled, you must type the Application Server user name and
password.
- 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

Perform the following steps to view information about failed events in
Failed Event Manager:
- On the Query page, select the information about the failed events that you
want to view:
- Event Status: select whether you want to view events with
the status of Failed, In Transit, Possible
Duplicate, Deferred, or Any of those four status
categories.
- Point of Failure: select the component in which the
failure occurred.
- Business Object: select a name of a business
object.
- Source Connector: select a name of an adapter or other
source connector.
- Select Date: click Any Time, or click Between
and select a beginning and end date and time.
- No. of events/page: Select how may events you want
to be displayed on each page of Failed Event Manager.
- 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

- 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

- 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

Perform the following steps in a Table of Failed Events to process failed
events:
- Select the check box in the left column for the failed events that you
want to work with.
- Do one of the following:
- To send the events back to the destination application, click
Submit. This action is available if you are assigned to a
role that can submit events.
- To refresh the selected events and then send them back to the destination
application, click Refresh & Submit.This action is
available if you are assigned to a role that can submit events.
- To cancel the selected events if they are long-lived business processes,
click Cancel Waiting.
- To delete the selected events, click Delete.
Perform the following steps to check the roles you are assigned for Failed
Event Manager role-base security:
- log on to Failed Event Manager (see Steps for logging on to Failed Event Manager).
- 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.
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
Perform the following steps to start Flow Manager:
- 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

- Enter the server name, using any one of the following methods:
- 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

Perform the following steps in Flow Manager to find all unresolved
flows:
- Start Flow Manager. See Steps for starting Flow Manager.
- Do one of the following:
- If you want to locate and display all unresolved flows, accept the
defaults of Any for all the fields.
- If you want to construct a query to find specific flows, refer to the
following sections that describe the search options in each tab:
- 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

- To save the current filter information as a query, click Query >
Save. The query name you type appears in the Query
list.
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:
- Status: Select events according to their status, which
you can designate as one of the following:
- Any: Selects all unresolved events.
- Failed: Selects all unresolved events that are in the
Failed state.
- In Transit: Selects all unresolved events that are in the
In Transit state.
- Possible Duplicate: Selects all unresolved events that
are in the Possible Duplicate state.
- Deferred: Selects all unresolved events in which the
point of failure was a collaboration with a recovery mode setting of
Deferred.
- Waiting: Selects all unresolved events in which the point
of failure was a collaboration with a recovery mode setting of Waiting.
- Event Owner: Select a collaboration name or a connector
name to query for flows that failed within that collaboration or
connector. You can string together multiple selections by clicking in
the new empty field that is created below each existing selection. To
search all of your collaborations and connectors, select
Any.
- Event: For each collaboration or connector that you
select, select an event, as represented by a business object. You can
select one event, string together multiple events, or select
Any.
- Verb:
Chose the verb to query for each event.
- Source Connector
Select the source connector or connector whose flows you want to query, or
select Any.
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:
- Any Time: Queries for all failed events, with no
restriction on when occurred
- Find all events: Queries for all failed events that
occurred within a specified time period:
- between (specified times)
- within (period of days)
- older than (number of days)
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:
- Business Object
- Attribute
- Operand
- Value
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.
Perform the following steps to view details for unresolved flows in Flow
Manager:
- Select a query from the Query list.
- Do one of the following:
- Click the Find button.
- Click Event > Find.
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:
- Event Status
- Event Owner
- Point of Failure
- Connector
- Event
- Time
- Message
- Key Attributes
For the waiting events, the Event Status cell contains the
following information:
Waiting
[timeout expiration:...]
[scenario name:...]
[scenario node ID...]
- 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

- 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.
Perform one of the following steps to manage queries you created for
unresolved flows:
- To save the current filter information as a query, click Query >
Save. The query you type appears in the Query
list.
- To delete a selected query in the Query menu, click Query
> Delete.
- To show or hide the content of the query, click Query >
Show/Hide.
Perform the following steps to manage queries you created for unresolved
flows:
- In the results list in Flow Manager, select one or more events in the
results list.
- Do one of the following:
- To delete selected events, click Event > Delete.
- To save all the failed events in the results list in an Excel file, click
Event > Save.
- To print the selected events to a table, click Event >
Print. A dialog box appears with Print All Events or
Print Selected Events options.
- To display the number of events corresponding to the current query, click
Event > Get Count.
- To clear all the result events, close the result list, and refresh all the
filter controls, click Event > New Search.
Perform the following steps to process any failed events in the results
list in Flow Manager:
- In the results list in Flow Manager, select one or more events in the
results list.
- Do one of the following:
- To send the data of the events back to the destination application, click
Event > Submit.
- To cancel waiting events (long-lived business processes), click Event
> Cancel Waiting.
- To refresh the data and then send the events back to the destination
application, click Event > Refresh & Submit.
