Provide information about managing the configuration of application domains and importing and exporting configurations.
v Appendix A, “Referenced objects,” on page 57
Provides detailed information about configuring objects that are referenced while developing services on a DataPower appliance.
v Appendix B, “Working with variables,” on page 147
Provides information about using variables in document processing.
v Appendix C, “Getting help and technical assistance”
Provides details about contacting IBM Support.
Publications
The IBM WebSphere DataPower library is organized into the following categories:
v “Installation and upgrade documentation”
v “Administration documentation”
v “Development documentation” on page vii v “Reference documentation” on page vii v “Integration documentation” on page vii
v “Problem determination documentation” on page viii v “Supplemental documentation” on page viii
Installation and upgrade documentation
v IBM WebSphere DataPower SOA Appliances: 9003: Installation Guide
Provides instructions for installing and powering up the Type 7993 (9003) appliance, creating a startup configuration script, and placing the appliance in operation.
v IBM WebSphere DataPower SOA Appliances: Type 9235: Installation Guide
Provides instructions for installing and powering up the Type 9235 appliance, creating a startup configuration script, and placing the appliance in operation.
v IBM WebSphere DataPower SOA Appliances: Type 9235: Hardware Problem Determination and Service Guide
Provides information about diagnosing and troubleshooting hardware problems, ordering consumable replacement parts, and replacing parts.
v IBM WebSphere DataPower SOA Appliances: Upgrade and Rollback Guide: Generation 2 Firmware
Provides instructions for upgrading Generation 2 firmware and for rolling back firmware upgrades.
Administration documentation
v IBM WebSphere DataPower SOA Appliances: Appliance Overview
Provides an introduction and understanding of the IBM Websphere DataPower SOA appliances.
v IBM WebSphere DataPower SOA Appliances: Administrators Guide
Provides instructions for using the DataPower GUI for managing user access, network access, appliance configuration and system configuration of the appliance.
v IBM WebSphere DataPower SOA Appliances: Hardware Security Module Guide A user guide for using a Hardware Security Module (HSM) installed in the appliance.
Development documentation
v IBM WebSphere DataPower SOA Appliances: XSL Accelerator Developers Guide Provides instructions for using the WebGUI to configure XSL Proxy and XSL Co-Processor services.
v IBM WebSphere DataPower SOA Appliances: XML Firewall Developers Guide Provides instructions for using the WebGUI to configure XML Firewall services.
v IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers Guide
Provides instructions for using the WebGUI to configure Web Application Firewall services.
v IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Provides instructions for using the WebGUI to configure Multiple-Protocol Gateway services.
v IBM WebSphere DataPower SOA Appliances: Web Service Proxy Developers Guide Provides instructions for using the WebGUI to configure Web Service Proxy services.
v IBM WebSphere DataPower SOA Appliances: B2B Gateway Developers Guide
Provides instructions for using the WebGUI to configure B2B Gateway services.
v IBM WebSphere DataPower SOA Appliances: Low Latency Messaging Developers Guide
Provides instructions for using the WebGUI to configure a DataPower appliance for low latency messaging.
Reference documentation
v Product-specific documentation for using commands from the command line.
The documentation is specific to each of the following products. Each document provides an alphabetical listing of all commands with syntactical and functional descriptions.
– IBM WebSphere DataPower XML Accelerator XA35: Command Reference – IBM WebSphere DataPower XML Security Gateway XS40: Command Reference – IBM WebSphere DataPower XML Integration Appliance XI50: Command Reference – IBM WebSphere DataPower B2B Appliance XB60: Command Reference
– IBM WebSphere DataPower Low Latency Messaging Appliance XM70: Command Reference
v IBM WebSphere DataPower SOA Appliances: Extension Elements and Functions Catalog
Provides programming information about the usage of DataPower XSLT extension elements and extension functions.
Integration documentation
The following documents are available for managing the integration of related products that can be associated with the DataPower appliance:
v Integrating with ITCAM
Provides concepts for integrating the DataPower appliance with IBM Tivoli Composite Application Management for SOA.
v IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere Transformation Extender
Provides concepts for integrating the DataPower appliance with WebSphere Transformer Extender.
v IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere MQ Explains the concepts and common use patterns for connecting DataPower services to WebSphere MQ systems.
Problem determination documentation
v IBM WebSphere DataPower SOA Appliances: Problem Determination Guide Provides troubleshooting and debugging tools.
Supplemental documentation
v Understanding Web Services Policy
Provides conceptual information about how the DataPower appliance can use Web Services Policy (WS-Policy).
v Understanding WS-Addressing
Provides conceptual information about how the DataPower appliance can use WS-Addressing.
v Understanding LTPA
Provides conceptual information about how the DataPower appliance can use Lightweight Third Party Authentication.
v Understanding SPNEGO
Provides conceptual information about how the DataPower appliance can use SPNEGO.
v Optimizing through Streaming
Provides conceptual information about and procedures for optimizing the DataPower appliance through streaming.
v Securing the Last Mile
Provides conceptual information about and procedures for understanding the DataPower appliance while securing the last mile.
v Configuring the DoD PKI
Provides conceptual information about and procedures for configuring the DataPower appliance with Department of Defense Public Key Infrastructure.
File naming guidelines
The maximum length for a file name can be approximately 4128 characters. The name of the base file can be up to 128 characters in length. The base file is the part after the name of the DataPower directory. Examples of directories are local:, store:, and temporary:.
If the directory (or domain) supports subdirectories, the path to the file can have a length of 4000 characters. When you create a domain, its name is the base file name in several DataPower directories when viewed from the default domain.
The following characters are valid in directory and file names:
v athrough z v Athrough Z v 0through 9 v _(underscore)
v -(dash) v .(period)
Note: Names cannot contain two consecutive periods (..).
Object naming guidelines
The object name must be unique in the object namespace. The following characters are valid in when specifying the name for an object:
v athrough z v Athrough Z v 0through 9 v _(underscore) v -(dash) v .(period)
Note: Names cannot contain two consecutive periods (..).
Typeface conventions
The following typeface conventions are used in the documentation:
bold Identifies commands, programming keywords, and GUI controls.
italics Identifies words and phrases used for emphasis and user-supplied variables.
monospaced
Identifies user-supplied input or computer output.
Chapter 1. WebGUI basics
The WebGUI is the primary interface for managing the appliance itself and for configuring objects.
Objects on the appliance
Objects that can be configured on the appliance range from simple to complex. An object is any entity that you configure on the appliance. During configuration, an object can reference another object that can, in turn, reference another object. For example, the configuration of a service references an instance of the XML Manager object that references an instance of the User Agent object. The flexibility in configuration and association of referenced object allow you to meet your business-processing criteria and security requirements.
Working with objects
When configuring services on the appliance, the WebGUI provides an object view and a service view. You can use either view to create or edit the service.
Service view
Working in the service view allows less-than-expert level users to build basic, generic objects.
Object view
Working in the object view allows expert-level users to build specific, complex and highly detailed objects.
Accessing the WebGUI
To use the WebGUI, the Web Management Interface must be configured. This interface was defined during the initial firmware setup (during appliance installation) or afterward with the web-mgmt command.
To access the WebGUI, use the following procedure:
1. Direct your browser to the WebGUI login screen. Use the IP address and port number assigned during the configuration of the Web Management interface.
The address uses the HTTPS protocol and has the https://address:port format.
2. In the login fields, specify an account name and password.
3. From the Domain list, select the domain to which to log in.
4. Click Login.
After verifying credentials, the WebGUI displays the Control Panel.
Welcome screen
After successfully logging in, the WebGUI displays its Welcome screen. Visibility of objects in the WebGUI is controlled by a combination of the Role-based
management (RBM) object and whether the administrator is in the default domain or an application domain.
This screen is separated into the following areas:
v The banner shows details about the administrator who logged in to the appliance and contains the following controls:
– The Domain list that allows the administrator to switch domains.
– The Save Config button that allows the administrator to persist configuration changes.
– The Logout button that allows the administrator to end the WebGUI session.
v The navigation bar along the left side provides access to related configuration suites and to related management suites. This area contains the following menus:
– The Control Panel returns the administrator to the Welcome screen.
– The Status menu provides access to logs and status providers.
– The Services menu provides access to service configuration objects and objects referenced by service objects. When the administrator selects the item, the WebGUI displays the service view for the object.
– The Network menu provide access to network configuration objects. These objects are to define the network in which the appliance connects. Many of these objects are available in the default domain.
– The Administration menu provides access to managing access to the appliance as well as general appliance settings. Many of these objects are available in the default domain.
– The Objects menu provides access to service configuration objects and objects referenced by service objects. When the administrator selects the item, the WebGUI displays the object view for the object.
v The dashboard that is separated into the following areas:
– The top area contains icons to access top-level objects for the appliance.
– The middle area contains icons to access monitoring and troubleshooting utilities.
– The bottom area contains icons to access file management and administration utilities.
When you click any icon on the dashboard or select any item from the menu, the WebGUI replaces the dashboard with the details for the selected item.
Common WebGUI conventions
In addition to the standard interface controls, the WebGUI uses custom controls to help during the configuration of objects. These controls generally pertain to defining referenced objects.
Working with referenced objects
When using the WebGUI to create and modify objects, the configuration screen might display an input field to select a referenced object. Figure 1 illustrates this type of input field.
When the WebGUI displays this type of input field, you can specify the referenced object in the following ways:
v Select the name of an existing referenced object from the list.
Figure 1. Input field for referenced objects
v Use the + button to create a new referenced object. When created, the input field contains the name of the newly created referenced object.
v Use the ... button to modify the referenced object whose name is in the input field. When modified, the input field retains the name of the referenced object.
When you click the + button or ... button, the WebGUI launches a new window that displays the configuration screen for that type of object.
Working with lists of referenced objects
When using the WebGUI to create or modify objects, the configuration screen might display an input list to define a group of referenced objects. The input for this configuration item is the list of referenced objects. Figure 2 illustrates this type of input list.
When the WebGUI displays this type of list, you can manage referenced objects in the following ways:
v Select the name of an existing referenced object from the list. Click Add to add it to the list of referenced objects.
v Use the + button to create a new referenced object. When created, the input field contains the name of the new referenced object. Click Add to add it to the list of referenced objects.
v Use the ... button to modify the referenced object whose name is in the input field. When modified, the input field retains the name of the referenced object.
Click Add to add it to the list of referenced objects.
v Select the name of a referenced object from the list (either the input field or the list of referenced objects). Click Delete to remove it from the list of referenced objects.
When you click the + button or ... button, the WebGUI launches a new window that displays the configuration screen for that type of object.
Viewing and editing local files during configuration
As you use the WebGUI to select a local file during configuration, the
configuration screen might display the View and Edit buttons beside the selection lists.
Working with files in this way has the following advantages:
v Ensure that the file is the one that you want
v Ability to edit the file to address errors found while defining a configuration v Use a single session instead of opening another session to manage files through
the File Management utility You cannot view or edit remote files.
Figure 2. Input list for referenced objects
Viewing local files
To view a local file, use the following procedure:
1. Select the file from the lists.
2. Click View to open the file editor in view mode.
3. Review the file.
4. Click Cancel.
Editing local files
The edited file overwrites the original file.
To edit a local file, use the following procedure:
1. Select the file from the lists.
2. Click Edit to open the file editor in edit mode.
3. Edit the file as required.
4. Click Submit to save changes.
5. Click Close.
Common WebGUI tasks
The majority of objects provide the following common tasks. Not all of these tasks are available to all objects.
v Applying and saving configuration changes
v Canceling changes before saving to the running configuration v Resetting changes to an object
v Deleting an object
v Exporting the configuration of an object v Viewing object-specific logs
v Viewing object status v Cloning a service
v Accessing probe captures
Applying and saving changes
As you use the WebGUI to manage object and service configurations, click Apply to save these changes to the running configuration. Changes that are made to the running configuration take effect immediately, but are not persisted to the startup configuration. During an appliance restart these changes are lost.
To retain applied changes across an appliance restart, click Save Config. The changes are saved to the startup configuration. The startup or persistent
configuration is persisted across an appliance restart. By default, the appliance reads the startup configuration from the auto-config.cfg file.
Canceling changes
As you use the WebGUI to manage objects, click Cancel to not save the current changes to the running configuration. If you click Cancel, you return to object catalog and lose all changes.
Resetting objects
Independent of whether the settings are saved to the configuration, you can reset an object to its default configuration.
Use the following procedure to revert changes to a specific object:
1. Display the catalog for the object. The catalog lists the available instances of this object.
2. Click the name of the object for which to reset to display the configuration screen.
3. Click Undo.
4. Follow the prompts.
Deleting objects
You might want to delete objects that are no longer needed. If no other object depends on the object to be deleted, you can delete it at any time. Because a DataPower service is a top-level object, you can delete it at any time. Conversely, you cannot delete an object that is active and that is in use by a higher-level object.
Use the following procedure to delete an object:
1. Display the catalog for the object. The catalog lists the available instances of this object.
2. Click the name of the object to delete to display the configuration screen.
3. Click Delete.
4. Follow the prompts.
Deleting an object deletes that object only. Deleting an object does not delete any referenced object.
Exporting objects
Use the following procedure to export an object:
1. Display the catalog for the object. The catalog lists the available instances of this object.
2. Click the name of the object to export to display the configuration screen.
3. Click Export.
4. Follow the prompts.
Viewing object-specific logs
Instead of filtering the log for the default log or a configured log target, you can view log messages that are specific to an object.
Viewing log files from the catalog
To view object-specific logs from the catalog, use the following procedure:
1. Display the catalog for the object. The catalog lists the available instances of this object.
2. Click the magnifying glass icon.
Viewing log files from the configuration screen
To view object-specific logs from the configuration screen, click View Logs.
Viewing object status
You can view the status of an object and all its referenced objects to help determine why a configuration object is in a down state. When you view the object status, the WebGUI opens a new window. This window provides the ability to show or hide unused properties.
v To show the unused properties, click Show.
v If the display lists unused properties, click Hide to hide these properties. Hiding unused properties is the default behavior.
When viewing the object status, the window provides the following information:
v The name of the instance and its type with a control to collapse (hide) or expand (show) referenced objects
v Its configuration state: New, Modified, or Saved v It operational state: up or down
v Its administrative state: enabled or disabled v Details about the detected error, if applicable
v A link (magnifying glass icon) to view the logs for this object Use the following procedure to view the status for an object:
1. Display the catalog for the object. The catalog lists the available instances of this object.
2. Click the name of the object to view to display the configuration screen.
3. Click View Status.
Cloning services
You might want to create a service that is similar to an existing service. For example, you need two equivalent services, but each service communicates with a different remote server. In these cases, you can create a clone of an existing service and edit the clone. The cloning process can expedite the creation of a similar service.
Use the following procedure to clone a server:
1. Display the catalog for the service. The catalog lists the available instances of this service.
2. Click the name of the service to clone to display the configuration screen.
3. Click Clone.
4. When the screen refreshes, specify the name of the clone.
5. Specify the Ethernet interface that the service monitors for incoming client requests in the Device Address field. Use the default address (0.0.0.0) to specify all interfaces.
6. Specify the Ethernet port that the service monitors for incoming client requests in the Device Port field.
7. As necessary, edit the other properties.
8. Click Apply to save the object to the running configuration.
9. Optionally, click Save Config to save the object to the startup configuration.
Accessing probe captures
After enabling the probe, defining the triggers, and sending transactions that match the conditions defined by the triggers, you can view the captured transactions.
Use the following procedure to access probe captures:
1. Display the catalog for the service object. The catalog lists the available
1. Display the catalog for the service object. The catalog lists the available