Biztalk Adapter Pack Migration Guide

Migration Guide for Microsoft BizTalk Adapters for Enterprise Applications

Microsoft Corporation Published: August 2010

1 Copyright Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted in examples herein are fictitious. No association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation. Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Microsoft, Windows, Windows Server, Windows Vista, Active Directory, BizTalk, Excel, SharePoint, SQL Server, Visual C#, and Visual Studio are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. All other trademarks are property of their respective owners.

2 Contents

3 1.Migrating Non-WCF Adapters to WCF (BizTalk) Platform

Documentation Feedback Microsoft values your feedback. To send feedback and comments about this topic to the documentation team, click here.

Introduction This document describes the process for migrating Microsoft® BizTalk® Adapters for Enterprise Applications projects to BizTalk Adapter Pack projects. For ease of reading/use, the rest of documents refer to:  Microsoft BizTalk Adapters for Enterprise Applications adapters as non- WCF LOB adapters  BizTalk Adapter Pack as WCF-based LOB adapters

The migration tool accepts BizTalk project/Solution files containing schemas generated by non-WCF based adapters and generates corresponding new BizTalk project/Solution files having schemas corresponding to the WCF-based adapters, with the maps and orchestrations modified accordingly.

The migration tool enables you to migrate the projects for the following adapters:  Oracle Database adapter  SAP adapter  SQL adapter

The migration tool allows you to:  Automate the most tedious tasks involved in migration – namely creating maps, adjusting references, etc.  Identify the artifacts that need to be changed when used with the new adapter: o Schemas o Orchestrations (if there are dependencies in the orchestration on the schema) o Maps to convert old schema to new schema

4 Checklist: Planning Your Installation Below is a list of prerequisites for running the migration tool. Ensure these are in place before running the migration tool.

Ensure the following are installed:  Microsoft BizTalk Adapter Pack 2010 or Microsoft BizTalk Adapter Pack 2.0  WCF LOB Adapter SDK 2010 or WCF LOB Adapter SDK SP2  BizTalk Server 2010, BizTalk Server 2009, or BizTalk Server 2006 R2  Visual Studio® 2010, Visual Studio 2008, Visual Studio 2005

Download migration tool: Download and extract the migration tool to a folder on your local computer.

5 Migrating a Non-WCF Adapter This section provides the step-by-step process of the Migration wizard. The steps to migrate non-WCF adapters to WCF-based adapters apply to all three adapters unless specifically noted.

To migrate a non-WCF adapter: 1. Run the BizTalkAdapterPackMigrationTool.exe. 2. On the Select Project screen a. Select the project to be migrated. You can either specify BizTalk Project (btproj) or a Visual Studio solution (sln) containing at least one BizTalk project. If non-BizTalk projects are present in the sln file, the solution file generated by the tool will reference the non- BizTalk projects from their old location. b. Specify the location where the new project should be created. By default, the tool creates a new folder “Migrated” in the same location as the old project.

Click Next.

On the Select Adapter Type screen: a. Select the adapter type to be migrated. b. Specify the connection URI and the credentials to the Line-of- Business (LOB) system. The tool uses this information to obtain the new schemas using the WCF-based adapter.

Click Next.

Note If the artifacts in the project are from multiple LOB servers, you need to run the migration process for each LOB server.

3. On the Shortlist Schemas screen, select old schemas to be migrated by checking the box next to the schema name.  The schemes which are already checked are the ones which have been verified by the tool to be present on the LOB server.  The unchecked schemas are the ones that couldn’t be verified for presence on the LOB server. Before checking them, please verify that the corresponding artifact (Table/Procedure etc.) is present on the specified LOB server.

Click Next.

6 Note If any of the checked artifacts are not present on the LOB server, the migration process will fail.

4. In the case of a SAP adapter project with IDOC schemas, you need to provide additional information on the Additional information about schemas screen: a. Release number of the IDOC. b. Version of the IDOC. c. Base type of the IDOC.  If it is an Extended IDCO type, you must provide the correct base IDOC value in the BaseType field.  If it is not an Extended IDCO type, leave BaseType blank.

Click Next.

5. Select the artifacts to migrate. You can opt for one of the following options: a. Generate new maps (i.e., from old to new schemas for outbound operations and vice versa.) These maps can be deployed in the physical port as Inbound/Outbound maps from the BizTalk administration console. In effect, the maps and orchestrations continue to use the old adapter schema.

b. Change the maps and orchestrations in the project to use the newly generated artifacts in addition to generating new maps. In this case:  All orchestrations and maps in the project are migrated to use the new adapter schema.  The old adapter schemas are preserved in the project and the tool creates maps from the old adapter schema to the new adapter schema. Note At times, messages going to the adapter come directly from some external system (without any mapping in BizTalk Server) and it is not possible to change the format of the incoming message to the new adapter format. Using these schemas and maps, you can receive the message in the old adapter format and using an Inbound map (deployed in the receive port), convert the message to the new adapter format (before the message gets submitted to BizTalk Server).

Click Next.

7 6. The tool displays the progress of the migration.  In case the migration fails, the process terminates and the migration log is displayed.  In case the migration completes, you can review generated files and the migration log.

Note The migration log file is stored at %Migrated Project Folder %/migrationLog.xml.

7. Click Finish to complete the migration process.

After running the migration tool: 1. Open the newly-created project in Visual Studio to verify the migrated project works as expected. 2. Migrate the components listed in the Limitations section manually. 3. Compile and deploy the newly created project. 4. In the BizTalk Administration console, import the newly-generated bindings file (%PROJECTNAME%)_Binding.xml). You may be required to correct BtsActionMapping on the port, in case the operation names in the generated BtsActionMapping are different from the operation names in your orchestration.

8 Note The binding file contains Information about physical Send Ports/Receive Ports which can be bound to the logical orchestration ports. The tool generates two kinds of send ports:  A set of physical send ports, which have a one-to-one mapping to their corresponding Orchestration ports. The BtsActionMapping is correctly set in these ports.  One physical port containing BtsActionMapping for all the generated schemas. This should be used if you don’t have orchestrations in your project (consuming the particular schema), or if the tool does not generate a physical port for a particular logical port in your project. You need to edit the btsActionMapping according to your requirements.

5. Specify the credentials for the newly-created send/receive ports. 6. Provide the additional parameters as required. For example, in case of the SAP adapter, the connection parameters exposed in the transport type configuration of old adapter is part of URI in the new adapter:

New adapter examples:  Application Server URI: sap://Client=800;lang=EN@A/SAPSYSTEM/SYSTEMID

 Message Server URI: sap://Client=800;lang=EN@B/MSGSERVER/R3NAME? Group=GroupName

The following table contains the mapping between parameters exposed by old adapter and the corresponding parameters in URI:

SAP non-WCF Adapter SAP WCF-based Adapter Program ID ListenerProgID SAP Gateway Host ListenerGwHost SAP Gateway Service ListenerGwServ

For more information regarding properties exposed by WCF-based SAP adapter (which are not supported by the old adapter), refer to "The SAP System Connection URI" at http://go.microsoft.com/fwlink/?LinkId=197488.

7. Configure the application by binding each logical port in orchestrations to their corresponding physical ports. 9 8. Start and run the application.

10 Limitations General  Promoted properties are not migrated. If the schemas generated by the old adapter contain some promoted properties, they are not promoted in the target schema.  Custom .NET code is not migrated. If any old adapter schemas are used in custom .NET component called from the orchestration, the custom .NET component will continue to reference the old schema. You need to manually change the custom code to use the new schema.  Pipeline components are not migrated. If any old adapter schema is used in some custom pipeline component, the custom pipeline component will continue to reference the old schema. You need to manually change the custom pipeline components.  Xpath Queries. If the orchestration contains Xpath queries which reference the old schema, they need to be manually edited to use the new schema.  If a message context property is being assigned in a Construct Message Shape inside an orchestration, and the value of the property has changed in the new adapter, then the migrated project continues to have the old value.

Note A lot of message context properties are assigned while using Dynamic Ports. As a result, automated migration of dynamic ports is not supported.

Note An exception to this is the SAPSend.ConnectionType which has been replaced by Microsoft.Adapters.SAP.BiztalkPropertySchema.Connect ionState. This property is migrated by the tool and the migrated project contains reference to the new value.

 If message text (conforming to the old schema) is hardcoded inside the Orchestration, is not modified as part of migration; you will have to modify it manually.

Note With BAPI transactions, it is a common practice to create the commit/rollback messages in the orchestration: xmlDoc.LoadXml(" X ");

This message has to be modified manually to confirm to new adapter schema.

 The expected exceptions/errors must be updated in the Orchestration because the exceptions are now thrown by the new adapter and will be different from those thrown by old adapter.  The tool adds some functoids for converting the date/time format of the old adapter to the new adapter. At compilation, these maps may throw a warning like:

The destination node "foo" has multiple inputs but none of its ancestors is connected to a looping functoid.

11 You can ignore this warning.

 The migration tool assumes that: a. For outbound operations in SQL and Oracle Database adapters: a.i. Request schema is always present on the destination side of maps (never on the source side). a.ii. Response schema is always present on source side of maps (never on destination side). b. For inbound operations in the Oracle Database adapter, the request schema is always present on the source side of the maps. Oracle Database Adapter  The Oracle Database Adapter’s input XML is not always validated. For example, processing the following via non-WCF adapter works well; however, this fails with the WC based adapter using the migrated project. 8016 …

 Table Select operation in the Oracle Database Adapter does not return ROWID. For more information, see http://go.microsoft.com/fwlink/?LinkId=152663. Table Select operation in the Oracle Database Adapter does not support MaxRows parameter, and is ignored by the tool in all Maps.  Automated migration of “SQLExecute” operation is not supported. You must manually modify the solution to use Oracle Database Adapter. For more information, see http://go.microsoft.com/fwlink/? LinkId=152662.  Automated migration of “SQLEvent” operation is not supported. You must manually modify the solution to use Oracle Database Adapter. For more information, see http://go.microsoft.com/fwlink/? LinkId=152660.  XMLType is not supported in the new Oracle Database Adapter. Hence, migration will fail if you try to migrate projects containing XMLType datatype.  Migration of projects with a "TopLevel" procedure node is not supported. o Invocation of procedures outside a package is not supported in non-WCF adapter, except against Oracle 8i. o The non-WCF adapter's MSB-GUI displays all the procedures that are outside a package under a single node called "TopLevel". However, the non-WCF adapter's MSB-GUI displays this node when using against post-8i database versions also. But at run time, calling these procedures will fail.

Note Oracle Database adapter is not supported against 8i due to client limitation.

12 SQL Adapter  The old SQL adapter throws the following warning if no data is found to update or delete: SQLOLEDB Error Description: Empty update, no updatable rows found Transaction aborted

SQLOLEDB Error Description: Empty delete, no deletable rows found Transaction aborted But the WCF-SQL adapter returns a response with '0', if it doesn't update or delete any row.

As the migrated project contains a map with WCF-SQL response schema to old SQL adapter response schema, you don’t get any warning for unsuccessful update or delete and also get a success response like below: 0

 The migration tool assumes that both the request and the response schema for an outbound operation reside in the same XSD file (this is the way schema is generated by the old adapter).  Old SQL adapter allows the symbols $, €, etc., in the input for data type money, whereas WCF-SQL adapter didn’t allow any symbols. You need to remove these symbols if any are present from the input for data type money while using the migrated project.  For stored procedures: o Stored procedures having a FOR XML clause: Maps are not migrated/ generated for response schema. You should use XMLProcedure which returns response in the format of old adapter schema. This allows the response to be backward compatible. For more information, see http://msdn.microsoft.com/en-us/library/dd787898.aspx. o Stored procedures not having a FOR XML clause: The tool maps the “Dataset” response of the new schema to the Success node of the response of the old Schema. You should use normal “Procedure” which returns response in DataSet format.

Note If you use XMLProcedure with stored procedures which don’t return any data, then the WCF-SQL adapter will throw XMLReader Parsing exception.

 The tool doesn’t migrate Polling operation (Select Statement or Inbound Stored Procedure). You must use XmlPolling which is backward compatible. The tool generates port bindings for the same. For more information, see http://msdn.microsoft.com/en-us/library/dd788084.aspx.

SAP Adapter  QRFCs are not supported by the WCF-based adapter, and hence migrated projects containing QRFCs won’t work with the WCF-based adapter.  The old adapter had the same schema for Remote Function Calls (RFCs) and Transactional 13 Remote Function Calls (TRFC). o The differentiation was made on the basis of a message context property- SAPSend.RFCType. o The new adapter does not have the context property SAPSend.RFCType. The context property SAPSend.RFCType must be manually removed from all message assignment shapes in the orchestration. o The new adapter has different schemas for RFCs and TRFCs and the differentionation between RFCs and TRFCs is made based upon the root namespace of the XML message.  The old adapter treated empty fields (like ) as null fields. o The new adapter throws an exception if the min length of such fields is greater than zero. o According to the SAP Binding’s design, if a field has an empty value, then that value is supposed to be valid. Hence, if you do not want to specify a value, you should suppress the field. Alternately, you should specify it as a null value (“nil”=”true” attribute).  The new adapter doesn’t allow a comma (,) as the decimal indicator. o The old adapter parsed the XML in a culture-specific format. So, the decimal indicator (comma (,) or period (.) was chosen based on the Regional Settings service user. o The new adapter follows the XML standard of using a period (.) as the decimal indicator, and throws an exception if an xs:decimal field has a comma(,).  The new adapter throws an exception for fields that have a data length larger than the max allowed length for the field. o The old adapter silently truncated data elements that were too long. o In the new adapter, you should trim data elements that are too long before they reach the adapter.

14 Binding Properties This section provides the old binding properties along with the corresponding newly generated properties.

Oracle Database Adapter

Outbound Old Transport Properties Corresponding New Binding Property/ Location Password Available from the Credentials Tab in the Consume Adapter Service plug-in in the WCF-Oracle Database adapter. PATH N/A Service Name Specified in connection URI. User Name Available from the Credentials Tab in Consume Adapter Service plug-in in the WCF-Oracle Database adapter. Max Concurrent Calls N/A Maximum number of sessions MaxPoolSize Event Log Level Part of tracing configuration. Refresh agent N/A Affiliate Application AffiliateApplication (‘Use Single Sign-On’ option under Credentials Tab in WCF-SAP adapter). Use SSO Available from the Credentials Tab in the Consume Adapter Service plug-in in the WCF-Oracle Database adapter. Use Transaction Use AmbientTransaction.

Inbound Old Transport Properties Corresponding New Binding Property/ Location Password Available from the Credentials Tab in the Consume Adapter Service plug-in in the WCF-Oracle Database adapter. PATH N/A Service Name Specified in connection URI.

15 Old Transport Properties Corresponding New Binding Property/ Location User Name Available from the Credentials Tab in the Consume Adapter Service plug-in in the WCF-Oracle Database adapter. Delete after poll User needs to explicitly provide delete logic in PostPollStatement. Event Max row count N/A Maximum number of sessions MaxPoolSize Poll SQL statement N/A (not supported in migration scenario) Polling interval PollingInterval Post Poll SQL statement N/A (not supported in migration scenario) Event Log Level Part of tracing configuration. Managing events Managing Events is not a Binding Property. It exposes the design time functionality that is equivalent to the receive-side MSB GUI. This will not be used. Refresh Agent N/A Affiliate Application Affiliate Application (‘Use Single Sign-On’ option under Credentials Tab in WCF-SAP adapter) Use SSO From the Credentials Tab in the Consume Adapter Service plug-in in the WCF-Oracle Database adapter.

SQL Adapter

Outbound Old Binding property New Binding Property Connection String Replaces with the Address (General Tab) + Credentials Tab in the Consume Adapter Service plug-in for the WCF-SQL adapter. Document Target Namespae Not configurable by user (No corresponding new binding property). Response Document Root Not configurable by user (No corresponding Element new binding property). 16 Inbound Old Binding property New Binding Property Poll While Data Found(Default = PollWhileDataFound (Default = false) false) Polling interval (Default =30) Polling IntervalInSeconds (Default = 30) Poling Unit of Measure(Default = Not Applicable seconds) Connection String Replaces with the Address (General Tab) + Credentials Tab in the Consume Adapter Service plug-in for the WCF-SQL adapter. Document Root Element Name XmlStoredProcedureRootNodeName Document Target Namespace XmlStoredProcedureRootNodeNameSpace SQL Command Polling Statement URI (Default = SQL://) Replaces with the Address (General Tab) in the Consume Adapter Service plug-in for the WCF-SQL adapter.

New binding property in WCF-SQL adapter (Inbound Operation) Binding property Explanation InboundOperationType (Default = Required value depends upon the actual Polling) operation being performed by the user. PolledDataAvailabeStatemant Required value depends upon the actual operation being performed by the user.

SAP Adapter

Outbound Old Binding property New Binding Property Client Client (Default =800) Language (Default EN) Language (Default EN) System ApplicationServerHost(Uri Property) (Default =SAPSERVER) SystemID (Default 00 ) SystemNumber (Default =00) SSO Affiliate AffiliateApplication (‘Use Single Sign-On’ option under Credentials Tab in WCF-SAP adapter) Group ApplicationServerGroupName 17 Old Binding property New Binding Property Message Server MessageServerHost R3 Name R/3 System Name Concurrent Connections MaxConnectionsPerSystem(Default =50) (Default = 0 (meaning unlimited)) Password Available from the Credentials Tab in the Consume Adapter Service plug-in in the WCF-SAP adapter. UserName Available from the Credentials Tab in the Consume Adapter Service plug-in in the WCF-SAP adapter.

Inbound Old Binding property New Binding Property Client Client (Default =800) SystemID (Default 00) SystemNumber (Default =00) Batch Size (Default =20 , though Not present in new adapter (WCF-based it shows up in UI as 1 ) adapters don’t support batching). Codepage (Default =0) Not Required in the new Adapter. Adapter figures this out dynamically. Language (Default= EN) Language (Default= EN) Password Available from the Credentials Tab in the Consume Adapter Service plug-in in the WCF-SAP adapter. ProgramID Program Id SAP Gateway Host GatewayHost SAP Gateway Service GatewayService UserName Available from the Credentials Tab in the Consume Adapter Service plug-in in the WCF-SAP adapter.

New binding property in WCF-SAP adapter (Both inbound and Outbound) EnableSafeTyping (Default = Required value = true false)

18 Note Other new binding properties introduced have default values which you can refer to in the CHM file that ships with the adapter.