Using the Partner Manager

Overview

The Partner Manager is a OnRamp for Commerce One MarketSite package (the WmPartners package) that manages the routing of documents based on a set of routing rules that you specify.

The Partner Manager:

Accepts documents that you submit to via a special service
Determines how the document is supposed to be routed
Routes the document to the appropriate destination
Tracks documents in its message store

How Does the Partner Manager Route a Document?

The Partner Manager determines how to route a document based on routing rules that you establish on your IBM webMethods Integration Server. When the Partner Manager receives a document, it looks for a routing rule that matches the following attributes of the incoming document:

Sender
Receiver
Message Type

When Partner Manager locates the routing rule that matches these criteria, it executes the routing action specified by that rule. Depending on how you define the rule, the routing action might deliver the document to:

A service on the local machine or a remote machine
An FTP location
An SMTP mailbox

Basic Steps to Use the Partner Manager

About this task

Before your site begins using the Partner Manager, you must decide where you want to maintain the Partner Manager’s message store—the place where the Partner Manager maintains an audit trail of documents that it processes. You can choose to maintain the message store in a log file on IBM webMethods Integration Server or in a JDBC-compatible database that you are already using at your site. For information about setting up the message store, Using the Message Store.

After you configure the message store, you can begin using the Partner Manager to automatically route documents based on their attributes. To do this, you need to take the following general steps for each type of document that you want the Partner Manager to route:

Procedure

Build a routing rule that defines the document’s Sender, Receiver , and Message Type attributes and specifies what action you want the Partner Manager to take when it receives documents matching those attributes. For information about building routing rules, see “Building and Maintaining the Routing Rules” on page 11Building and Maintaining the Routing Rules.
Build the service that will be used to submit the document to the Partner Manager. For information about handing documents to the Partner Manager, see Submitting Documents to Partner Manager.

Building and Maintaining the Routing Rules

Routing rules tell the Partner Manager what to do with documents it receives. A routing rule has two basic elements: routing criteria and routing action.

The routing criteria specify the sender, receiver, and message type values that cause the routing action to occur.
The routing action is encompassed in a flow service (called the routing service). This service performs any pre-processing actions that you specify and then invokes the outbound transport, which delivers the document to its intended destination.

Components of a Routing Rule

You use the Integration Server Administrator to create, edit, and view routing rules. Each routing rule has the following basic components.

Number	Description
1	The routing criteria—the sender, receiver, and message type values that trigger the action specified by the rule.
2	The ACL, package, and name of the routing service associated with the rule. This is the actual service that the Partner Manager invokes when it receives a document matching the rule’s routing criteria. The Partner Manager generates this service based on the action parameters you specify when you create a routing rule. You do not build this service manually.
3	The names of the pre- and post-processing services, if any, that the Partner Manager will execute before and after delivering the document to its destination. If either of these services fail, the transaction status will change to reflect the service failure. A pre-processing service is a service that you build to perform any work that must be executed immediately before the Partner Manager sends a document out. For example, you might use a pre-processing service to affix a digital signature to a document or mark it with a special postmark. A post-processing service is a service that you build to perform any work that must be executed immediately after the Partner Manager sends a document out. The use of these services is purely optional.
4	The transport that Partner Manager will use to deliver the document to its destination.
5	Addressing parameters that describe the document’s specific destination. These parameters vary depending on the transport you select. For example, when you choose the Email transport, these parameters specify a host system and a particular mailbox; when you use the IS Service transport, they identify a particular service on a IBM webMethods Integration Server.

The Routing Criteria

The routing criteria—the Sender, Receiver, and Message Type values—determine which rule is selected at run time. They uniquely identify a routing rule and act as the trigger for the rule’s routing action. You can also use a wildcard character (*) to match all Sender, Receiver, or Message Type values.

This parameter...	Specifies...
Sender	An arbitrary string that identifies who sent the document, or a wildcard character (*).
Receiver	An arbitrary string that identifies the document’s destination, or a wildcard character (*).
Message Type	An arbitrary string that specifies what type of information is in the document (e.g., a purchase order, a credit memo, an invoice, and so forth), or a wildcard character (*).

As noted previously, the values that you use as routing criteria are arbitrary or they can be wildcards (*). They do not need to specify a physical address or document. The routing criteria should match the sender, receiver, and msgType values that are submitted with the document. For example, if your trading partner submits invoices under a sender value of MtnPaintPurch003, a receiver value of BboardsAP, and a msgType of Invoice, the Sender, Receiver, and Message Type values in your routing rule must match these strings letter for letter. (These values are case sensitive).

Using Wildcards as Routing Criteria

You can use a single asterisk character (*), known as a wildcard, for the Sender, Receiver, and Message Type values in a routing rule. A wildcard matches any value that may be submitted with an incoming document. Some uses for wildcards include:

Use a wildcard for the Sender parameter to serve as a “catch all” routing rule for a specific company. For example, suppose that you want to execute a particular routing rule for all documents from XYZ Company. You don’t necessarily want to define routing rules for each message type that might be sent from XYZ Company, so you use the wildcard character (*) for the Message Type.
Use a wildcard for all parameters (Sender, Receiver, and Message Type) to serve as a “last resort” routing rule. This routing rule will be executed when all other routing rules do not match the incoming document.

Routing Rule Precedence

A routing rule is executed when its Sender, Receiver, and Message Type values match an incoming document’s values. When one or more of those values is a wildcard (*), then the routing rule is matched and executed based on its value precedence. See the following table for the default match order. The most specific rule is matched (and executed) first.

A rule with these values is matched...	Sender	Receiver	msgType
First	`arbitrary string`	`arbitrary string`	`arbitrary string`
Second	*	`arbitrary string`	`arbitrary string`
Third	`arbitrary string`	*	`arbitrary string`
Fourth	`arbitrary string`	`arbitrary string`	*
Fifth	*	*	`arbitrary string`
Sixth	*	`arbitrary string`	*
Seventh	`arbitrary string`	*	*
Eight (last)	*	*	*

Note: If rule matching is performed by an external service via a getRule service, then the value precedence is dependent on your custom implementation. A custom getRule service uses wm.PartnerMgr.gateway.getRule:getRuleSpecification to bypass the default routing rule functionality and returns the routing rule that you want invoked. The getRule service must be specified in the server.cnf file on the watt.WmPartners.getRule parameter. Any kind of wildcards can be implemented within the getRule service.

Example 1

Suppose that you have a routing rule with the following values:

Sender=snd

Receiver=receiver

msgType=msg1

If a message arrives with the following values:

Sender=snd1

Receiver=receiver

msgType=msg1

and a routing rule does not exist with those exact values, then the message will be matched to a routing rule with the following pattern:

Sender=*

Receiver=arbitrary string

msgType=arbitrary string

Example 2

Suppose that you have a routing rule with the following values:

Sender=snd

Receiver=receiver

msgType=msg1

If a message arrives with the following values:

Sender=snd1

Receiver=receiver

msgType=msg2

and a routing rule does not exist with those exact values, then the message will be matched to a routing rule with the following pattern:

Sender=*

Receiver=arbitrary string

msgType=*

To override the default match order, see Overriding Routing Rule Match Order.

When an Inbound Message Contains a Wildcard

If an inbound message contains an asterisk (*) for its receiver or msgType parameters, then the Partner Manager creates a mailbox directory on the server, replacing “*” with “WildCard”. This is necessary because file systems do not allow special characters for directory or file names.

For example, suppose that you have a routing rule with the following values:

Sender=*

Receiver=Rcv

msgType=*

If a message arrives with the following values:

Sender=sender

Receiver=Rcv

msgType=*

then the corresponding .values file is stored in the mailbox at: \..\packages\WmPartners\pub\mailbox\Rcv\WildCard

The Routing Service

All of the action associated with a particular routing rule is encompassed within its routing service. The routing service executes the pre-processing service specified by the rule (if any), invokes the transport service, which delivers the document to a specified destination, and then executes the post-processing service specified by the rule (if any).

The following example shows the contents of a routing service. In this example, the routing service invokes a pre-processing service (TStamp) and then submits the document to the transport service (OutboundProcess).

The Partner Manager automatically generates a routing service when you create a routing rule. You do not build routing services manually, although you can use Designer to edit the services that the Partner Manager builds.

With respect to routing services, keep the following points in mind:

You can use Designer to view the contents of a routing service.
You can use Designer to incorporate additional pre- or post-processing steps into the routing service; however, you must insert your changes after the MAP step that appears at the top of the flow. For additional information about adding steps to a routing service, see Editing a Routing Service.
You must not rename a routing service after you create a routing rule. Doing so will cause the routing rule to fail at run time because the Partner Manager will not be able to locate the service named in the routing rule.

Note: If the routing rule contains a wildcard character for the Receiver or Message Type, the routing service name will have “WildCard” in the name, instead of “*”.

Pre-Processing Services

When you define a routing rule, you can optionally instruct the Partner Manager to execute a pre-processing service before routing a document to its destination. For example, you might use a pre-processing service to obtain a special timestamp or affix a digital signature to the document. Because the document exists in the pipeline when the Partner Manager invokes the pre-processing service, you can even use this service to extract information from, or write information to, the document itself.

When you specify the name of a pre-processing service in the routing rule, the Partner Manager executes that service before it invokes the transport—that is, in the routing service, the invocation step for the pre-processing service appears before the invocation step for the transport service.

The Transport Service

The transport service (usually referred to simply as, the transport) performs the actual work of delivering a document to a specified destination.

When you create a routing rule, you specify which transport you want the Partner Manager to use to deliver the document. You also specify addressing information that the transport needs to deliver the document to the appropriate destination (e.g., a mailbox, file location, or service) at run time.

The following table identifies the transports you can use to deliver a document.

You use this transport...	To pass the document to...
IS Service	A specified service on the local Integration Server or on a remote Integration Server.
Email	A specified mailbox as an e-mail attachment using the Simple Mail Transfer Protocol (SMTP).
FTP	A specified file location using the File Transfer Protocol (FTP).

Post-Processing Services

When you define a routing rule, you can optionally instruct the Partner Manager to execute a post-processing service after routing a document to its destination.

When you specify the name of a post-processing service in the routing rule, the Partner Manager executes that service after the Outbound Process is complete in the routing service.

When a Routing Rule Does Not Exist

If the Partner Manager receives a document for which a routing rule does not exist (that is, it cannot locate a rule matching the document’s sender, receiver and msgType values), the Partner Manager creates an incomplete routing rule—a rule with no action associated with it—for that document.

Viewing Incomplete Rules Created by the Partner Manager

When you view the list of routing rules on your Integration Server, incomplete routing rules appear with a red Status icon in the View Routing Rules screen.

An incomplete rule contains routing criteria (which was derived directly from the submitted document) but no routing action.

You use Integration Server Administrator to edit an incomplete rule and define its routing action (i.e., make it a complete, and therefore valid, routing rule). This will allow the Partner Manager to successfully route subsequent documents whose attributes match the rules’ Sender, Receiver, and Message Type values. For information about editing an incomplete routing rule, see Activating an Incomplete Routing Rule.

Note: There may be times when you want to deliberately trigger the Partner Manager’s incomplete rule-generating capability. For instance, if a document’s Sender, Receiver, and Message Type values are not known, you can quickly and accurately capture that information in a routing rule by simply submitting the document to the Partner Manager. An alternative is to use wildcard characters in the routing rule.

Creating a Routing Rule

About this task

Use the following procedure create a routing rule.

Important: You must have administrator privileges on Integration Server to execute the following procedure.

This procedure requires you to select the package in which you want the rule’s routing service registered. If this package does not already exist, create it before you begin. If you need procedures for creating a package, see IBM webMethods Integration Server Administrator’s Guide, or the IBM webMethods Service Development Help for your release.

To create a routing rule

Procedure

Start Integration Server Administrator.
On the Adapters menu, click Routing.
On the View Routing Rules screen, specify the routing criteria in the three text boxes under the Sender, Receiver, and MsgType columns, and click Add Rule.

Remember that these values should match the sender, receiver, and msgType values that will be submitted with the document, or a wildcard character (*). These values are case sensitive.

On the Edit Routing Rule screen, set the following Routing Rule Flow parameters to specify where you want the routing service created.

In this field...	Do the following...
ACL Group	Select the ACL group to which you want to limit the routing service access. Only the users that are in groups that are in the selected ACL list will be able to use this service.
Package	Select the package in which you want the Partner Manager to register the routing service it generates.
Main flow service	Accept the default service name suggested by the Partner Manager or type a new, fully qualified name for the routing service. (This is the name that the Partner Manager will assign to the flow service it generates to perform the routing action. By default, the Partner Manager suggests a name that incorporates the sender, receiver, and message type information.) Important: If Sender, Receiver, or Message Type contains characters that your file system does not support, be sure to modify the suggested name to eliminate those characters. For example, if the message type were “XML\PurchaseOrder”, you would eliminate the \ from the suggested service name. If Receiver or Message Type contains a wildcard character (*), then the Partner Manager automatically replaces it with “WildCard” in the service name.

If you want the routing service to invoke a pre-processing or post-processing service, type the fully qualified name of that service in the Pre-Processing Service field and Post-Processing Service field.

Select the transport that you want to use to deliver the document.

Select this transport...	To...
Service	Pass the document to a specified service on a local or remote Integration Server.
Email Outbound Service	Send the document to a specified mailbox as an attachment to an e-mail message using the Simple Mail Transfer Protocol (SMTP).
FTP Outbound Service	Send the document to a specified file location using the File Transfer Protocol (FTP).

Configure the transport as described in the following sections, then click Save.

To configure the...	See this section...
IS Service transport	Configuring the IS Service Transport
Email transport	Configuring the Email Transport
FTP transport	Configuring the FTP Transport

Results

The routing rule appears in the View Routing Rules screen. By default, it is disabled. You can enable it by clicking No in the Enabled? column. Once enabled, it changes to Yes.

Configuring the IS Service Transport

About this task

Use the following procedure to complete the configuration parameters on the Edit Routing Rule screen if you are creating a routing rule that uses the IS Service transport. The IS Service transport passes the document to a specified service on a local or remote Integration Server.

To configure the IS Service transport, in the Configure IS Service section of the Edit Routing Rule screen, complete the following fields:

In this field...	Do the following...
Server Alias	Select the Integration Server on which the service resides, or select (local) if the service resides on the same server as the Partner Manager. (If the Integration Server you need does not appear in this list, you must create an alias for it. For information about defining aliases for remote Integration Servers, refer to the IBM webMethods Integration Server Administrator’s Guide for your release.)
Folder	Type the name of the folder in which the service resides.
Service	Type the name of the service to which you want to pass the document.
Scope	Specify how you want to maintain the routing service’s connection information in cases where the document is routed to a service on a remote server. Select SESSION if you want to maintain connection information within the routing service’s session. This preserves this information for the routing service’s exclusive use while it is connected to the remote server. Use this option if the routing service will perform stateful interactions with the remote server. Select GLOBAL if you want to maintain connection information in a shared session pool, making it available for use by other services that may need to connect to the same server. Because the data in this session is not protected from other services, you should only use this option if the routing service’s interaction with the remote server is stateless (i.e., it is not dependent on the availability of session information after a connection has been established).

Configuring the Email Transport

About this task

Use the following procedure to complete the configuration parameters on the Edit Routing Rule screen if you are creating a routing rule that uses the Email transport. The Email transport sends the document to a specified mailbox as an attachment to an e-mail message.

To configure the Email Transport, in the Configure Email Outbound Service section of the Edit Routing Rule screen, complete the following fields.

In this field...	Do the following...
SMTP Host	Type the host name of the SMTP server to which you want the document delivered.
Content Type	Type the string that will be used to specify the content type of the e-mail message. For example: `application/x-edi-message`
From	Type the e-mail address that you want to use as the sender of the e-mail message. For example: `orderingsystem@buyer.com`
To	Type the address of the mailbox where you want the document delivered. For multiple mailboxes, separate each address with a comma. For example: `orders@seller.com,purch@buyer.com`
CC	If you want to send a copy of the message to another mailbox, type the address of that mailbox. For multiple mailboxes, separate each address with a comma. For example: `acctpayable@buyer.com,receiving@buyer.com.`
BCC	If you want to send a blind copy of the message to another mailbox, type the address of that mailbox. For multiple mailboxes, separate each address with a comma. For example: `manager@buyer.com,log@buyer.com`
Subject	Type the string that you want to appear as the subject line in the e-mail message.

Configuring the FTP Transport

About this task

Use the following procedure to complete the configuration parameters on the Edit Routing Rule screen if you are creating a routing rule that uses the FTP transport. The FTP transport sends the document to a specified file location on an FTP server.

To configure the FTP transport, in the Configure FTP Outbound Service section of the Edit Routing Rule screen, complete the following fields.

In this field...	Do the following...
Host Name	Type the host name of the remote FTP server.
Port Number	Type the port number on which the remote FTP server listens for FTP requests.
User Name	Type the user ID that the Partner Manager must submit in order to connect to the FTP server.
Password	Type the password that the Partner Manager must submit in order to connect to the FTP server.
File Path	Type the directory in which you want the document transferred. The transport will automatically assign a file name to the file it puts in this directory. The name will have the format, “ftpfile`xx`.data”, where `xx` is an ID that the FTP transport assigns.

Activating an Incomplete Routing Rule

About this task

Use the following procedure to complete the definition of an incomplete routing rule. An incomplete routing rule is a rule that the Partner Manager automatically generates from a document whose sender, receiver, and msgType values do not match any of the existing rules. (For more information about what causes Partner Manager to generate incomplete routing rules, see When a Routing Rule Does Not Exist.) To complete the rule, you must specify the routing action associated with the routing criteria.

To complete an incomplete routing rule

Procedure

Start Integration Server Administrator.
On the Adapters menu, click Routing.
On the View Routing Rules screen, locate the incomplete rule that you want to edit. (Incomplete rules have a red indicator in the Status column.)
Click the Edit icon for the rule.
On the Edit Routing Rule screen, set the Routing Rule Flow and Transport parameters as described in Creating a Routing Rule.
Click Save.

Viewing the Routing Rules

About this task

Perform the following procedure to view the list of existing routing rules.

To view routing rules

Procedure

Start Integration Server Administrator.
On the Adapters menu, click Routing. The View Routing Rules screen appears.
If you want to sort the list, click the up or down arrow icons in the column headings.

Overriding Routing Rule Match Order

About this task

When routing rules contain wildcards for the Sender, Receiver, or Message Type, there is a default order in which the routing rule is matched to the incoming document’s values. (For details, see Routing Rule Precedence.) You can override this default order by modifying the RoutingRulePriorityTemplate.cnf file in your WmPartners package. See the following procedure.

To override routing rule match order

Procedure

In a text editor such as Notepad, open the following file: Integration Server_directory\packages\WmPartners\config\RoutingRulePriorityTemplate.cnf

Edit the file to reflect the match order priority that you want for rules containing wildcards. See the following table.

This character in the file...	Represents...
`#`	A comment. Put at the beginning of a line that contains a comment.
`S`	The `sender` value.
`R`	The `receiver` value.
`M`	The `msgType` value.
`*`	A wildcard. It will match any value.

Save the file.
In Integration Server Administrator, under Packages, click Management.
Next to WmPartners, click the Reload icon. The new routing rule match order is now in effect.

Note: If rule matching is performed by an external service via a getRule service, then the value precedence is dependent on your custom implementation. A custom getRule service uses wm.PartnerMgr.gateway.getRule:getRuleSpecification to bypass the default routing rule functionality and returns the routing rule that you want invoked. The getRule service must be specified in the server.cnf file on the watt.WmPartners.getRule parameter. Any kind of wildcards can be implemented within the getRule service.

Editing a Routing Rule

About this task

You can use the following procedure to edit a routing rule and change its routing action.

Note that once you create a routing rule, you cannot modify its routing criteria. If you need to change the rule’s criteria, you must delete the existing rule and create a new rule based on the new criteria.

Note: When you modify a rule’s routing action, the Partner Manager updates the rule’s routing service. However, the changes you make only affect the first step in this service. If you added your own steps to the routing service, they will not be altered. For information about editing the routing service directly, see Editing a Routing Service.

To edit a routing rule

Procedure

Start Integration Server Administrator.
On the Adapters menu, click Routing. The View Routing Rules screen appears.
Locate the rule that you want to edit. Click the Edit icon for the rule.
Edit the Routing Rule Flow and Transport parameters as necessary. If you need additional information about these parameters, see Creating a Routing Rule.
Click Save.

Disabling Routing Rules

About this task

Use the following procedure to disable a routing rule. When you disable a routing rule, all routing service and rule information is preserved until you re-enable it.

To disable a routing rule

Procedure

Start Integration Server Administrator.
On the Adapters menu, click Routing. The View Routing Rules screen appears.
Locate the rule that you want to disable. Under Enabled?, click Yes until it turns to No.

Deleting Routing Rules

About this task

Use the following procedure to delete a routing rule.

Important: When you delete a routing rule, the Partner Manager deletes the routing service associated with that rule.

To delete a routing rule

Procedure

Start Integration Server Administrator.
On the Adapters menu, click Routing. The View Routing Rules screen appears.
Locate the rule that you want to delete. Click the Delete icon for the rule.

Editing a Routing Service

About this task

When necessary, you can edit a routing service with Designer to incorporate additional steps before or after the transport delivers the document. For example, you might want to insert flow-control steps (for example, LOOP or BRANCH steps) around the pre- or post-processing services, or you might want to include some error-handling steps immediately after the transport service.

Guidelines to Follow When Editing a Routing Service

When you edit a routing service, keep the following points in mind:

Do not add any flow steps before the first MAP step.
Do not modify the pre-processing service’s label property (if a pre-processing service exists in the flow).
Do not modify the transport service’s label property.

Submitting Documents to Partner Manager

Submitting a Document to the Partner Manager

About this task

To submit a document to the Partner Manager, you create a flow service that invokes the following service:

wm.PartnerMgr.gateway.transport.B2B:InboundProcess

Your flow service must pass the document to this service, along with the appropriate sender, receiver, and message type values. The InboundProcess service invokes the Partner Manager, which inspects the document’s sender, receiver, and message type values and selects the routing rule matching those values.

Passing a Document to the Transport Service

About this task

When you invoke InboundProcess, the Partner Manager receives the entire contents of the pipeline, including your document. However, you need to pass your document to the Partner Manager where the transport service expects it.

The following table describes where the Partner Manager expects the document for each transport type.

This Transport...	Sends…
IS Service Transport	The entire pipeline to the specified service. When a document is routed with this transport, it doesn’t make any difference where you put it in the pipeline, because the entire pipeline is transmitted to the destination service.
Email Transport	The contents of `data/content` to the specified email address, where `data` is an IS Document (an IData object) and `content` is an object element of `data`. If your document will be routed through the email transport: It must be in the form of a String, a byte [ ], or an InputStream. You must map the document to `data/content` before invoking the Partner Manager.
FTP Transport	The contents of `data/content` to the specified file location, where `data` is an IS Document (an IData object) and `content` is an object element of `data`. If your document will be routed through the FTP transport: It must be in the form of a String, a byte [ ], or an InputStream. You must map the document to `data/content` before invoking the Partner Manager.

Building a Service that Invokes the Partner Manager

About this task

To build a flow service that submits a document to the Partner Manager

Procedure

Use Designer to create a new flow service.
Insert the flow steps that your service will use to generate or retrieve the document that you want to submit to the Partner Manager. For example, if the document will originate from an ERP system such as Baan or PeopleSoft or from a database, build the invoke and data-transformation steps that will retrieve and generate the document at run time.

The following example shows a flow service that extracts a single document from the database (in this case, a PO) and converts it to an XML document. (Although an XML document is generated in this example, you can submit any type of data to the Partner Manager. It does not have to be an XML document.)
If you will use the Email or FTP transport to route the document to its destination, do the following:
1. Add a map step that creates an IS Document (IData object) called data.
2. Within data, create an object called content.
3. Map your document (which must be a String, or an object that contains a byte [ ] or an InputStream) to data/content.
The following shows how the MAP step is used to map the XML document generated by documentToXMLNode from the preceding example, to data/content.
Insert a step that invokes wm.PartnerMgr.gateway.transport.B2B:InboundProcess

Use the Pipeline Editor to set (or map) the following InboundProcess input values.

In this parameter…	Specify…
`sender`	The string that you are using to represent the sender. This value is what the Partner Manager will use to match the Sender value in its routing rules.
`receiver`	The string that you are using to represent the receiver of this document. This value is what the Partner Manager will use to match the Receiver value in its routing rules.
`msgType`	The string that you are using to represent the type of document you are submitting to the Partner Manager. This value is what the Partner Manager will use to match to the Message Typevalue in its routing rules.
`$routeOnly`	Optional. Whether you want the Partner Manager to log the document in its message store. Valid values are: `true` Route the document without logging it in the message store. The `$routeOnly` parameter must exist in the pipeline for this to take effect. `false` Log the document in the message store to the message store when it is routed.This is the default value. `no value` Log the document in the message store to the message store when it is routed.
`$tid`	Optional. A string that specifies the transaction ID that you want Partner Manager to the document when it puts it in the message store. Used only when `$routeOnly` is false or doesn’t exist in the pipeline. If you do not specify a transaction ID and `$routeOnly` is false or doesn’t exist, the Partner Manager automatically generates a transaction ID for the transaction.
`$action`	Optional. One of the following action codes that sets the state of the document when it is put in the message store. Used only when `$routeOnly` is false or doesn’t exist. Set the value to assign a state as follows: `0` Create `1` Execute `2` Rollback `3` Commit `4` Confirm

Note: You might want to drop any unused variables from the pipeline before invoking InboundProcess, especially if the document will be routed to another service on a remote server. This will prevent Partner Manager from unnecessarily sending data across the network.

The figure that follows shows a finished flow service that generates and submits a document to the Partner Manager. (In this example, the sender, receiver, and msgType parameters already exist in the pipeline, so they are implicitly mapped to those parameters in InboundProcess.)

Using the Message Store

What Is the Message Store?

When you submit a document to the Partner Manager, you can optionally instruct the Partner Manager to log a copy of that document in its message store. The message store is a facility that maintains a document of transactions that the Partner Manager processes. Each transaction document in the message store contains a copy of the document that was submitted to the Partner Manager, along with its routing parameters and an audit trail describing how the document was processed.

You use Integration Server Administrator to view the contents of the message store.

By viewing the message store, you can determine if and when the Partner Manager handled a particular document. You can also determine whether the Partner Manager processed a particular document successfully or returned an error.

Location of the Message Store

By default, the Partner Manager maintains the message store in the xtn.log file, which resides in the Integration Server_directory\packages\WmPartners\config directory on your IBM webMethods Integration Server. However, you can optionally configure the Partner Manager to maintain this information in a JDBC-compliant database, such as Oracle 6.0 (or higher), Informix 7.0 (or higher), or MS SQL Server 6.50.201 (or higher). For information about how to configure your system to use a database for the message store, see Using a Database as the Message Store.

Transaction IDs Identify Documents in the Message Store

Individual documents in the message store are uniquely identified by their transaction IDs (tid). A transaction ID is an arbitrary string that you can assign to the document before submitting it to the Partner Manager or you can allow the Partner Manager to assign to a document automatically. For information about assigning a transaction ID to a document, see the $tid parameter under Submitting a Document to the Partner Manager.

Logging a Document in the Message Store

When you submit a document to the Partner Manager, you specify whether or not you want that document recorded in the message store by setting the $routeOnly parameter. The Partner Manager only records documents whose $routeOnly parameter is set to “false” or when the $routeOnly parameter doesn’t exist in the pipeline. If you submit a document with $routeOnly set to “true” (i.e., $routeOnly exists in the pipeline), the Partner Manager processes the document without logging it into the message store.

For additional information about setting the $routeOnly flag when submitting a document to the Partner Manager, see the $routeOnly parameter under Submitting a Document to the Partner Manager.

Note: Once a document is written to the message store, the Partner Manager never removes it. The message store will grow continually unless you periodically purge the documents that are no longer needed. For information about deleting transactions from the message store, see Deleting a Single Transaction from the Message Store and Purging All Transactions from the Message Store.

Configuring the Location of the Message Store

About this task

You can configure the Partner Manager to maintain the message store in a log file (xtn.log) on IBM webMethods Integration Server or in a JDBC-compliant database that you have installed at your site.

If you want the Partner Manager to maintain its message store in the xtn.log file, you do not need to perform any special configuration steps to set up the message store. The Partner Manager will automatically use xtn.log as the message store unless you specifically configure it to use a database.
If you want the Partner Manager to maintain its message store in a JDBC-compliant database, you must configure the database server and IBM webMethods Integration Server as described in the following sections.

Important: To maintain the message store in a JDBC-compliant database, you must have the WmDB package installed and enabled on your Integration Server.

Using a Database as the Message Store

About this task

If you want to maintain the message store in a JDBC-compliant database that is installed at your site, you must take the following general steps to identify the location of that database. For more information about specific steps for Microsoft SQL Server 7 and Oracle 8i, see Configuring the Message Store on Microsoft SQL Server 7.x and Configuring the Message Store on Oracle 8i.

Important: Do not use a database with either the Microsoft or SUN built-in JDBC-ODBC bridge because these bridges can cause problems with IBM webMethods Integration Server.

Note: If Integration Server cannot establish a connection to the database for any reason, the message store will be automatically switched to the file system.

Configuring the database server

About this task

On the database server

Procedure

Establish a user account that Partner Manager can use to access the database.

Have your database administrator create the following tables in the database. Make sure that the user account you created in the previous step has read and write access to these tables.

Table	Columns	Type	Length
WMTRANSACTION_Log	tid	VARCHAR	50
	creationdate	DATE
	message	VARCHAR	255
WMTransactions	tid	VARCHAR	50
	sender	VARCHAR	50
	receiver	VARCHAR	50
	msgType	VARCHAR	50
	package	VARCHAR	50
	docURI	VARCHAR	50
	flow	VARCHAR	50
	lastError	VARCHAR	50
	state	INTEGER
	wmTime	DATE

Configuring IBM webMethods Integration Server

About this task

On IBM webMethods Integration Server

Procedure

Install a pure JDBC driver (for example the weblogic.jdbc.mssqlserver4.Driver from WebLogic or a comparable driver from a vendor such as Merant or Imprise) that IBM webMethods Integration Server can use to access the database server. (Make sure to add this driver to the server’s classpath.)
Check that the WmDB package is installed and enabled on your Integration Server. Then use Integration Server Administrator to define an alias for the database server.
Add the following statement to the server.cnf file:

watt.PartnerMgr.xtn.store=db

Configuring the Message Store on Microsoft SQL Server 7.x

About this task

Use the following procedures to maintain the Partner Manager’s message store in a SQL Server 7.x database.

Configuring the SQL Server

About this task

To use an SQL 7.x database as the message store, configure the SQL Server as follows

Procedure

Create a user account that the Partner Manager can use to access the database.
Create a user-defined data type named Date that has the data type “datetime.”

Create the following tables and give the Partner Manager’s account read/write access to them.

Table	Columns	Type	Length
WMTRANSACTION_Log	tid	VARCHAR	50
	creationdate	DATE
	message	VARCHAR	255
WMTransactions	tid	VARCHAR	50
	sender	VARCHAR	50
	receiver	VARCHAR	50
	msgType	VARCHAR	50
	package	VARCHAR	50
	docURI	VARCHAR	50
	flow	VARCHAR	50
	lastError	VARCHAR	50
	state	INTEGER
	wmTime	DATE

Note: If you grant the Partner Manager’s user account permission to create tables, the Partner Manager will automatically create these tables for you the first time it connects to the database.

Configuring IBM webMethods Integration Server

About this task

On IBM webMethods Integration Server

Procedure

Obtain a pure JDBC driver (for example, the weblogic.jdbc.mssqlserver4.Driver from WebLogic or a comparable driver from a vendor such as Merant or Imprise).

Important: The Microsoft SQL Server 7.x ODBC driver is not compatible with JDBC.
Install the driver according to the vendor’s installation instructions.
Edit the server.bat file (under Windows) or the server.sh file (under Unix) and add the JDBC driver to the classpath statement. (These files reside in the Integration Server_directory\bin directory.)

Start Integration Server Administrator and use the Database command on the Adapter menu to define an alias (a named set of connection parameters) called “transactions” for the SQL Server database. When you add this alias, specify the following information in the Details section of the New DB Alias screen. For more information about adding an alias for a database server, see the WmDB User’s Guide.

In this field...	Specify...
Alias	The following string: `transactions` Type this string exactly as it appears above, using only lowercase letters.
DB URL	The URL for the SQL Server database. Example: `jdbc:weblogic:mssqlserver4:edi:1433.`
DB Username	The user ID that you created for the Partner Manager in step 1 of Configuring the SQL Server. This is the user ID that the Partner Manager will use to connect to the SQL Server database. Note: When the Partner Manager connects to the database, it attempts to create the message store tables if they do not already exist. Before using the Partner Manager with SQL Server for the first time, make sure that the tables listed in step 3 of Configuring the SQL Server exist on the SQL server or that the user ID specified in DB URL is authorized to create tables.
DB Password	The password associated with the user account specified in DB Username.
Minimum Connections	The minimum number of connections to pool.
Maximum Connections	The maximum number of connections to have in the pool. When the maximum number of connections are open, then the next call to get a connection from the pool will wait until a connection is available (that is, re-added to the pool).
Expiration Time (ms)	The amount of time to wait before discarding a cached connection from the pool.
Loaded Drivers	The class name of the JDBC driver. Example: `weblogic.jdbc.mssqlserver4.Driver`

Edit the server configuration file to enable database logging. To do this, open Integration Server_directory\config\server.cnf with a text editor and add the following statement to it:
watt.PartnerMgr.xtn.store=db

Configuring the Message Store on Oracle 8i

About this task

Use the following procedures to maintain the Partner Manager’s message store in an Oracle 8i database.

Configuring the Oracle Database Server

About this task

To use an Oracle 8i database for the message store, configure the Oracle database server as follows

Procedure

Create a user account that the Partner Manager can use to access the database.

Create the following tables and give the Partner Manager’s account read/write access to them.

Table	Column	Type	Length
WMTRANSACTION_Log	tid	VARCHAR	50
	creationdate	DATE
	message	VARCHAR	255
WMTransactions	tid	VARCHAR	50
	sender	VARCHAR	50
	receiver	VARCHAR	50
	msgType	VARCHAR	50
	package	VARCHAR	50
	docURI	VARCHAR	50
	flow	VARCHAR	50
	lastError	VARCHAR	50
	state	DECIMAL
	wmTime	TIMESTAMP

Note: If you grant the Partner Manager’s user account the permission to create tables, the Partner Manager will automatically create these tables for you the first time it connects to the database.

Configuring IBM webMethods Integration Server

About this task

On IBM webMethods Integration Server

Procedure

Install the Oracle 8i thin driver classes111.zip file.
Edit the server.bat file (under Windows) or the server.sh file (under Unix) and add the JDBC driver to the classpath statement. (These files reside in the Integration Server_directory\bin directory.)

Start Integration Server Administrator and use the Database command on the Adapter menu to define an alias (a named set of connection parameters) called “transactions” for the Oracle database. When you add this alias, specify the following information in the Details section of the New DB Alias screen. For more information about adding an alias for a database server, see the WmDB User’s Guide.

In this field...	Specify...
Alias	The following string: `transactions` Type this string exactly as it appears above, using only lowercase letters.
DB URL	The URL for the Oracle database, which is usually specified in the following format: `jdbc:oracle:thin:username/password@hostname:portnumber:DatabaseName` where: `username` and `password` are the username and password you want to use to log on to the server. These are generally not needed, since the database framework will use the DBUsername and the DBPassword fields. `hostname` is the host name of the Oracle server. `portnumber` identifies the port on which the Oracle server listens for incoming requests. `DatabaseName` is the name of the database.
DB Username	The user ID that you created for the Partner Manager in step 1 of Configuring the Oracle Database Server. This is the user ID that the Partner Manager will use to connect to the Oracle database. Note: When the Partner Manager connects to the database, it attempts to create the message store tables if they do not exist. Before using the Partner Manager with Oracle 8i for the first time, make sure that the tables listed in step 2 of Configuring the Oracle Database Server exist on the Oracle server or that the user ID specified in DB URL is authorized to create tables.
DB Password	The password associated with the user account specified in DB Username.
Minimum Connections	The minimum number of connections to pool.
Maximum Connections	The maximum number of connections to have in the pool. When the maximum number of connections are open, then the next call to get a connection from the pool will wait until a connection is available (i.e., re-added to the pool).
Expiration Time (ms)	The amount of time to wait before discarding a cached connection from the pool.
Loaded Drivers	The class name of the JDBC driver. Example: `oracle.jdbc.driver.OracleDriver`

Edit the server configuration file to enable database logging. To do this, open Integration Server_directory\config\server.cnf with a text editor and add the following statement to it:

watt.PartnerMgr.xtn.store=db

Viewing the Message Store

About this task

Use the following procedure to view a list of the documents that the Partner Manager has logged into the message store and to examine the details (including the sender, receiver, message type, and error information) for a particular document.

To view the transactions in the message store

Procedure

Start Integration Server Administrator.
On the Adapters menu, click Routing.
Click Transactions. The contents of the message store appears. Documents are identified by transaction ID.
If you want to sort the list, click the up or down arrow icons in the column headings.
If you want to view details about a particular document, click its transaction ID (in the TID column).
If you want to view the body of the document (in addition to additional transaction information that was present at run time), click one of the following options in the View field:
- To view the transaction information in webMethods standard HTML-encoded format, click As XML or As Values.
- To view the transaction information in a special HTML format that displays the body of the document in a text box, click As HTML.

Deleting a Single Transaction from the Message Store

About this task

Use the following procedure to delete a transaction from the message store.

To delete a transaction from the message store

Procedure

Start Integration Server Administrator.
On the Adapters menu, click Routing.
Click Transactions. Locate the transaction that you want to delete.
Click the Delete icon for the transaction.

Purging All Transactions from the Message Store

About this task

There are two procedures to periodically purge the message store. The following procedure, which is recommended, uses the wm.PartnerMgr.xtn.Sweeper:sweepTRX service to periodically purge the message store of transactions.

Purging All Transactions from the Message Store Periodically

About this task

To purge all transactions from the message store periodically

Procedure

In Designer, create a flow service that invokes the wm.PartnerMgr.xtn.Sweeper:sweepTRX service.

Pass the following parameters to the sweepTRX service.

For this parameter...	Specify
onState	The transaction state
elapsedTime	The number of minutes that the transaction has been in onState
maxTrxCount	The maximum number of transactions to delete each time that sweepTRX is invoked

When the sweepTRX service is invoked, the System finalizer is invoked and the garbage collector is invoked.

Schedule the flow service to run periodically to purge the message store.

Example

If you want to periodically purge all transactions which have been in the Confirmed state for longer than 30 minutes, you can create a service called purgeConfirmedTRX with those state and time parameters. You also specify how many transactions every invocation of the service will purge. This is so you can control the pace of your maintenance jobs without increasing the amount of overhead processing.

The following procedure deletes all transactions manually from the message store. Use this procedure only to delete a small number of documents. Otherwise, server performance can degrade substantially.