Troubleshooting the BizTalk Adapters

For the latest version of Commerce Server 2007 Help, see the Microsoft Web site.

This topic contains descriptions of a variety of issues related to the BizTalk adapters that are provided with Commerce Server, also known informally as Commerce Server adapters. In most cases, a solution or workaround is provided also.

Unexpected Failure When You Try to Update Purchase Order Properties

If you have unexpected failures when you try to update purchase order properties by using the CommerceServerOrdersUpdateOrderProperties message, make sure that the XML element and attribute names in the body of your message are using the exact uppercase and lowercase spellings that the Commerce Server Orders System expects. For example, the Commerce Server Orders System expects the order group identifier attribute name to be specified exactly as "OrderGroupId." If your CommerceServerOrdersUpdateOrderProperties message uses "OrderGroupID" instead, the Commerce Server Orders System, for better or worse, throws an exception that indicates that OrderGroupId is missing from the XML BLOB.

The solution to this kind of problem is to make sure that the XML messages that you send to Commerce Server through the Commerce Server adapters use the exact uppercase and lowercase spellings that are in the XSD files supplied or generated by Commerce Server.

Fewer Than Expected Query Results from the Profiles Send Adapter

If you are using the Profiles send adapters to query the Commerce Server Profiles System and you receive fewer items in your query results than you expect, the problem could be the maximum result limit that is specified for the Profiles Web Service. The recommended solution to this issue is to use a dedicated Profiles Web Service that uses an increased maximum result limit that is large enough to handle your largest expected query results.

Failed to Submit Errors from the Orders Adapter

If you are using the Orders Adapter to submit messages to BizTalk you may sporadically see failure to submit messages (typically " The Web Service could not enlist in the transaction as requested"). The Orders Web Service server will report a "TxHelperCallFailure" error. This error can occur repeatedly until the Orders Adapter is restarted. This error occurs when a Load Balancer attempts to switch servers during execution of the BizTalk Adapter transaction. The recommended solution to this issue is to point the Commerce Server BizTalk adapter to one of the Web service servers specifically through the Load Balancer.

Unexpected Failure When You Try to Exchange Orders Between Two Instances of Commerce Server

If you are using the Orders adapter to send orders between two instances of Commerce Server, and the exporting instance of Commerce Server is configured to export one order per message, you will have to work with the root element of the message within BizTalk Server, for example by using BizTalk Mapper. Specifically, you must change the root element from OrderGroups (plural) to OrderGroup (singular) before importing it into the second instance of Commerce Server. If you do not perform this transformation, you will generate the following error:

• Specified Xml is invalid. The root node OrderGroups is not an OrderGroup derived type.

Passwords Not Written to BizTalk Server XML Bindings Files

If you use the BizTalk Server feature that enables you to export the bindings for a BizTalk application or group, and you have configured passwords for either of the transport properties Web Service Password or Proxy Password in the Commerce Server adapter endpoints that are being included in the bindings export, the created XML bindings file will not work as exported. This is because BizTalk Server takes the security precaution of not writing passwords out into a plain-text file. Instead it writes a series of asterisk characters (*) where the password or passwords would have otherwise occurred in the file. Safe as this is, it does prevent the XML bindings file from being imported, as is, into another BizTalk Server installation to re-create your bindings in that environment.

The recommended solution to this problem is to change the file to restore the passwords after the file has been moved to the system upon which you will import the bindings. After you open the file in an application such as Notepad, search for the string "******" and replace all such strings in the appropriate adapters configuration areas with the correct password.

Unexpected Web Service Authorization Errors at Run Time

When a Commerce Server adapter endpoint is not authorized to access its corresponding Commerce Server Web service, it is shut down and an error message is written to the event log. When this occurs, consider whether the BizTalk Server host instance account under which this adapter endpoint is running has different credentials than you used when you originally configured the adapter endpoint. You can solve authorization errors such as these by using one of the following methods:

• Providing the values for the Web Service Username and Web Service Password transport properties of the relevant Commerce Server adapter endpoint. These values should specify the credentials of a user who is authorized to use the required Web service APIs.

• Using Authorization Manager to grant the appropriate user rights to the account under which the BizTalk Server host instance is running.

For more information about the APIs used by Commerce Server adapters, see BizTalk Adapters Authorization Requirements.

Aborted Transactions When Using the Orders Adapter

When the Commerce Server Orders send adapter sends a message to Commerce Server to be processed in a Commerce Server orders pipeline, the processing of that message can fail in several ways. If the pipeline fails with a warning error level of 2, the transaction will be aborted and the Orders adapter will return the purchase order/basket with an error code of either Basket_Errors or PurchaseOrder_Errors.

If the pipeline fails with an error level of 3 or more, the Orders System will end the transaction and throw an exception. The adapter will return a response message that has its context property CommerceServerCommandResults set to AcceptBasketXmlException. This response message will have the exception message in the message body.

Abandoned Registry Entries

There are several situations in which the registry entries associated with Commerce Server adapters might be considered abandoned. First, the registry subkey specified during the configuration of a Commerce Server adapter endpoint might be created before creating the endpoint itself is finished. This can occur if you click Apply when configuring the transport properties for the adapter endpoint, but then cancel creating the containing receive location or send port. Also, if you delete a receive location or send port that has been successfully created, the registry subkey that you configured for that endpoint is not automatically cleaned up.

You can manually delete unused registry subkeys associated with defunct adapter endpoints, or select different subkeys for any subsequently created adapter endpoints.

The registry subkeys for the Commerce Server adapters are always created in the following registry location:

• HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Commerce Server 2007 BizTalk Adapters\

Using Tracing to Track Down BizTalk Adapter Problems

When integrating Commerce Server together with other systems by using the Commerce Server adapters, you may want to trace the activity of the adapters. There are two parts to this tracing. First, there is tracing the Commerce Server components, and second there is tracing within BizTalk Server. Each of these tracing activities is discussed separately later in this topic.

Tracing the Commerce Server Components

The Commerce Server adapters use the same tracing functionality as the rest of Commerce Server, with one minor difference. Whereas other Commerce Server components use fixed GUIDs as their trace identifiers, the Commerce Server adapters create a new trace GUID for each adapter endpoint that you create and configure. These dynamic trace GUIDs are stored in the registry for each endpoint under the Registry Subkey value that you provided as part of the endpoint configuration.

To trace a specific adapter endpoint, follow these steps:

1. Get its trace GUID from the registry. Look in the following registry path to find and retrieve the relevant trace GUID:

   • x86: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Commerce Server 2007 BizTalk Adapters\adapter_type\subkey\Trace Guid

   • x64 (running as a 32-bit process): HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Commerce Server 2007 BizTalk Adapters\adapter_type\subkey\Trace Guid

     In both cases, adapter_type is either Orders, Catalog, Inventory, or Profiles, and subkey is the value that you provided for the Registry Subkey transport property for the adapter endpoint in question.

2. Open a Command Prompt window and set %Commerce_Server_Root%\Support as the current directory.

3. To start a trace for a Commerce Server adapter endpoint (with, for example, the GUID 43914661-5C3B-4ccb-BD14-7BC8CFB76E13), use the following command:

   tracelog -start AdapterTrace -f AdapterTrace.log -guid #43914661-5C3B-4ccb-BD14-7BC8CFB76E13 -flags 0x7F

   Note

   Replace this example GUID with the trace GUID you retrieved from the registry in step 1.

4. Enable the corresponding adapter endpoint or submit an adapter message to generate trace data.

5. When you are ready to stop this trace, use the following command:

   tracelog -stop AdapterTrace

   A file that is named AdapterTrace.log that contains your trace data has been created in the current folder.

6. In order to read the trace information, you must format it using the following command:

   tracefmt AdapterTrace.log -tmf TraceFormat\CSTraceEvents.tmf

Tracing within BizTalk Server

In the BizTalk Server installation folder, there is a trace tool named Trace.cmd that uses standard Windows tracing technology. For more information, see the Using the BizTalk Adapter Trace Utility topic in the BizTalk Server 2006 Help. You can also run the trace command together with the -? option.

Last Run Times Written to the System Registry

Each Commerce Server adapter records the date and time at which it last ran in its configured location in the system registry. This information may prove useful when tracking down issues related to the adapters. It is stored under the registry key DateTime Of Last Run in the registry location you have configured for the corresponding adapter endpoint using the transport property Registry Subkey. The value of this property is used to create a unique registry location for the endpoint within one of the following four registry locations, depending on the type of the adapter:

• HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Commerce Server 2007 BizTalk Adapters\Catalog

• HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Commerce Server 2007 BizTalk Adapters\Inventory

• HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Commerce Server 2007 BizTalk Adapters\Orders

• HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Commerce Server 2007 BizTalk Adapters\Profiles

See Also

Other Resources

Performance Considerations for the BizTalk Adapters

Concurrency Issues with the BizTalk Adapters

Developing with the BizTalk Adapters