There is a lot of inconsistent and incorrect information about the BizTalk SAP Adapter (or in this case WCF-SAP Adapter) installation process and how it works – It is normal to see comments that the adapter only runs on 32-bit, or to see indications that we have to copy DLLs to two different places (System32 and SysWOW64) but which ones?

I hope with this step-by-step installation guide to clarify a bit and document a little better this task.

So, one of the key question that we need to clarify is: Does the WCF-SAP adapter runs under 64-bit Host Instance?

And the correct response to this question is: Yes, it does! The SAP adapter supports both the 32-bit and the 64-bit versions of the SAP RFC SDK, so it can run under 32 or 64-bit Host Instances.

The second important question that we need to clarify is that: Documentation specifies that we need to add the 32-bit version of the client DLLs for the SAP adapter to C:\Windows\SysWow64 folder and the 64-bit version of the DLLs must be added to C:\Windows\System32 folder, but what this means? Do need to add the same DLL in two different folders?

Indeed, the documentation is correct and we need to add both 32 and 64-bit to different folder in our system… but this are different DLL and no the same ones – so if you only have one SDK resource, for example the SAP RFC SDK 32-bit, you just need to add this into one of the folders, copy for both places doesn’t make any difference because the adapter will only run in this case under a 32-bit Host Instance.

For each SAP Client version (6.4, 7.0 and so on) there are two SAP RFC SDK one for 32-bit and one for 64-bit and you need to download and install both… just like the BizTalk Server Adapter Pack.

There are SAP UNICODE and NON-UNICODE, so witch version of the SAP RFC SDK should I download?

The SAP adapter requires Unicode version of the RFC SDK irrespective of whether the SAP system is Unicode or non-Unicode.

Official documentation states that only the following SAP server versions are supported:

  • SAP 7.2, SAP 7.0, SAP ERP 6.0 with EHP 4.0, SAP ECC 6.0 Unicode

However earlier version, which were mentioned in previous versions of the documentation, are also supported:

  • SAP ECC 5.0 Non-Unicode, SAP ECC 5.0 Unicode, SAP R/3 4.7 Non-Unicode, SAP R/3 4.7 Unicode, SAP R/3 4.6c Non-Unicode, SAP ERP 6.0 with EHP 4.0

Also official documentation states that the only supported client version is the SAP RFC SDK 7.2 UNICODE – I always recommend to use the latest version… however, once again, as previous versions of the documentation mentioned, these client versions are also supported:

  • SAP client 6.4 version: SAP RFC SDK 6.40 UNICODE
  • SAP client 7.0 version: SAP RFC SDK 7.00 UNICODE
  • SAP client 7.1 version: SAP RFC SDK 7.10 UNICODE
  • SAP client 7.11 version: SAP RFC SDK 7.11 UNICODE

I’m not a SAP expert but I think that all depends if the SAP client version is supported in your SAP System version. For example, in one BizTalk Server 2013 R2 environment I have the SAP client 7.2 version installed and in another one, a BizTalk Server 2013, I have the 7.0 and both are working fine.

And finally: Can I install only the 64-bit version?

No, you can’t and for the exact same reason that we need to install both version of the BizTalk Server Adapter Pack: Visual Studio and BizTalk Administration console are 32-bit applications, so in order to configure the adapter in runtime (Receive Locations or Send Ports that will be using the SAP Adapter) or to use it to generate the schemas in the development phase you always need to have installed the 32-bit version of the SAP RFC SDK.

The 64-bit version of the SAP RFC SDK is optional, but, if you have a 64-bit BizTalk environment and you want to run it under 64-bit Host Instance, then you need to also install both versions of the SAP RFC SDK.

Download Prerequisites

As happen with other LOB adapters (like Oracle for example), installing the BizTalk Adapter pack is not enough and you will need the addition resources that will be specify bellow.

Download SAP Resources from SAP Service Marketplace

You need to obtain a few resources from the SAP Service Marketplace in order to properly install WCF-SAP adapter:

  • SAP RFC SDK <version> UNICODE 32-bit
  • SAP RFC SDK <version> UNICODE 64-bit
  • R3DLLINST.zip containing Microsoft run-time DLLs
  • SAPCAR – SAPCAR is a compress utility (similar to WinZip, tar and so on), that is used by SAP to compress and decompress nearly all delivered files

Unfortunately, SAP Service Marketplace is restricted, so if you like to benefit from the content and services offered in the different portals of the SAP Service Marketplace, you need to request your personal User ID otherwise you need to ask your client or your SAP team to give you this resources.

In additional to the links above you may also find useful to give these two SAP notes to your client or SAP team:

Unlike R3DLLINST.zip, that is a unique resource, on the SAP Service Marketplace portal SAP RFC SDK page you will find several resources and we must understand exactly what we need, in this case for example purposes, I’m using the SAP RFC SDK 7.20 page:

SAP-Service-Marketplace-portal-SAP-RFC-SDK-7.20

Depending in the SAP client version you want to install this may change a little, but it is practically the same for the other versions, as you can see in the case of SAP RFC SDK 7.00 page

SAP-Service-Marketplace-portal-SAP-RFC-SDK

What you need to download is the:

  • Windows Server on IA32 32bit” –> this is the SAP RFC SDK 7.00 UNICODE 32-bit
  • And the “Windows on x64bit” –> SAP RFC SDK 7.00 UNICODE 64-bit

You also need to download SAPCAR to extract (unzip) the SAP resources, I think you may found this resource at service.sap.com/patches under:

  • Download, Support Packages and Patches, Entry by Application Group, Additional Components and then SAPCAR

SAP-Service-Marketplace-portal-SAPCAR

Extract SAP Resources

Once we have downloaded all this SAP resources, we need to use the SAPCAR to extract the SAP resources, in this case (SAP RFC SDK 7.20):

  • “RFC_12-10009744.SAR” is the 64-bit SDK that we want to extract to “rfcsdk 64” folder
  • “RFC_12-100097446.SAR” is the 32-bit SDK that we want to extract to “rfcsdk 32” folder

BizTalk-Server-SAP-Software-resources

To accomplished that we need to:

  • Open a command line prompt
  • Change our directory to the location where we saved the “SAPCAR.exe” and execute the following command to extract the the SAR archive:
    • SAPCAR.exe -xfv “RFC_12-10009744.SAR”
      • This will create a folder call “rfcsdk”, rename that to “rfcsdk 64”

Extract-SAR-archive-with-SAPCAR

    • SAPCAR.exe -xfv “RFC_12-10009746.SAR”
      • This will create a folder call “rfcsdk”, rename that to “rfcsdk 32”

The final step regarding to SAP Resource is to unzip the “r3dllinst.zip” file using for example an open source Windows utility for manipulating archives like 7-Zip.

Download Microsoft Visual C++ 2005 SP1 Redistributable Package

Microsoft Visual C++ run-time DLLs, again both 32 and 64-bit are required for SAP 7.11 client or higher. This resources are available from download in the following links:

download-Microsoft-Visual-C  _2005_SP1_Redistributable_Package

download-Microsoft-Visual-C  _2005_SP1_Redistributable_Package-files

Step-by-Step WCF-SAP Adapter installation guide

The first thing you need to make sure that you have installed already is both 32 and 64-bit versions of the Microsoft BizTalk Adapter Pack.

  • The Microsoft BizTalk Adapter Pack contains adapters that enable enterprise applications and databases to interface with each other by implementing a common adapter framework. Similar to programming to Web services, adapters enable clients to program to different enterprise applications. Technically, adapters are a binding to Windows Communication Framework (WCF). The BizTalk Adapter Pack consists of the following adapters:
    • Microsoft BizTalk Adapter for Oracle Database (Oracle Database adapter).
    • Microsoft BizTalk Adapter for Oracle E-Business Suite (Oracle E-Business adapter).
    • Microsoft BizTalk Adapter for mySAP Business Suite (SAP adapter). This also includes the .NET Framework Data Provider for mySAP Business Suite (Data Provider for SAP).
    • Microsoft BizTalk Adapter for Siebel eBusiness Applications (Siebel adapter). This also includes the .NET Framework Data Provider for Siebel eBusiness Applications (Data Provider for Siebel).
    • Microsoft BizTalk Adapter for SQL Server (SQL adapter).
  • Find more about the BizTalk Adapter Pack installation process in the following articles:

Notice that, at this point, if you try to create a receive or send port using the WCF-SAP adapter you will get the following error:

Exception has been thrown by the target of an invocation. (mscorlib)
Could not load file or assembly ‘Microsoft.Adapters.SAP.SAPGInvoker.dll’ or one of its dependencies. The specified module could not be found. (Microsoft.Adapters.SAP)

Could-not-load-file-assembly-Microsoft.Adapters.SAP.SAPGInvoker.dll

This is because we need the SAP resources required to run the adapter are not install (or are i installed incorrectly).

So, now that we have install the Microsoft BizTalk Adapter Pack, we need to install the SAP Resources that we previous download in our BizTalk Server machine:

  • Open the “rfcsdk 64” folder containing the SAP RFC SDK 7.20 UNICODE 64-bit and access to the lib folder
    • “C:\SAP Resources\rfcsdk 64\lib”

SAP-rfcsdk-7.2-64-bit-lib-Resources

  • Install the SAP RFC SDK 64-bit DLLs by coping (or drag) them to the “System32” folder in your system “Windows” folder
    • “C:\Windows\System32”:

SAP-rfcsdk-7.2-64-bit-lib-Resources-Installation

  • And now we need to do the a similar process to the Open the SAP RFC SDK 7.20 UNICODE 32-bit
  • For that you need to open the “rfcsdk 32” folder containing the SAP RFC SDK 7.20 UNICODE 32-bit and access to the lib folder
    • “C:\SAP Resources\rfcsdk 32\lib”

SAP-rfcsdk-7.2-32-bit-lib-Resources

  • Install the SAP RFC SDK 32-bit DLLs by coping (or drag) them to the “SysWOW64” folder in your system “Windows” folder
    • “C:\Windows\SysWOW64”:

SAP-rfcsdk-7.2-32-bit-lib-Resources-Installation

  • Open the “r3dllinst\ ntpatch” folder containing the content of “r3dllinst.zip” file, ,and we need to execute the “R3DLLINS.EXE” tool, in order to install the SAP R/3 DLLs (Microsoft run-time DLLs):
    • msvcr71.dll
    • msvcp71.dll
    • mfc71.dll
    • mfc71u.dll

install-SAP-r3dllinst-R3DLLINS

  • The tool specifies that the DLLs were installed under “C:\Windows\System32” folder, however because I’m using a 64-bit environment instead they were installed in “c:\Windows\SysWOW64” folder

install-SAP-r3dllinst-R3DLLINS-SysWOW64

    • You should check if DLL are present in “C:\Windows\System32”, if they are not I advise you to:
      • Leave them in the ” c:\Windows\SysWOW64” folder
      • And, just to be sure, copy the same four DLLs to “C:\Windows\System32” folder

install-SAP-r3dllinst-R3DLLINS-windows-folder

  • And finally we also need to installed Microsoft Visual C++ 2005 SP1 Redistributable Package – 32-bit and 64-bit – containing the Visual C++ run-time DLLs required for SAP 7.20 (or 7.11) client:
    • Install the Microsoft Visual C++ 2005 SP1 Redistributable Package (x86) – 32-bit – by executing the “Vcredist_x86.exe” file that we previous download
      • On the Microsoft Visual C++ 2005 SP1 Redistributable Package window, click “Yes”

Microsoft-Visual-C  -2005-SP1-Redistributable-Package-x86

    • Do the same steps to install the Microsoft Visual C++ 2005 SP1 Redistributable Package (x64) – 64-bit – by executing the “Vcredist_x64.exe” file that we previous download
      • On the Microsoft Visual C++ 2005 SP1 Redistributable Package window, click “Yes”
Add adapters to BizTalk Administration Console

As it happens with all adapters that we installed on our BizTalk Servers environment, before we can begin to use them we need to register or add the adapters. So in the next step it will be describing how can we add the enterprise adapters, or any other custom adapter, on the BizTalk Administration Console. To accomplish that we need to:

  • Open BizTalk Administration Console by pressing the “Windows key” to switch to the Start screen, type “BizTalk Server Administration” or “BizTalk”, click “BizTalk Server Administration” option from the Search menu
  • In the console left tree, expand “BizTalk Server Administration –> BizTalk Group –> Platform Settings” and then “Adapters”
  • Right-click on “Adapters” and add a new adapter by selecting the option “New –> Adapter”

BizTalk-Administration-Console-Register-WCF-SAP-adapter-add-new

  • In the “Adapter Properties” window
    • In the Name box, type a descriptive name for this adapter.
      • WCF-SAP
    • In the Adapter combo box, select the adapter from the drop-down that you want to add.
      • WCF-SAP
    • In the Description box, type a description for the adapter (this is optional).
      • The WCF-SAP adapter provides a rich metadata layer on top of SAP that enables the consumption of RFCs and enables seamless BAPI and IDOC exchange in an interoperable manner. The SAP adapter exposes the SAP system as a WCF service to client applications.

BizTalk-Administration-Console-Register-WCF-SAP-adapter

    • Click “OK” to complete the process of adding the adapter.
      • We will receive a warning message saying that we need to restart the Host Instances
      • Click “Ok”, we will deal with it in a moment

BizTalk-Administration-Console-Register-WCF-SAP-adapter-warning-message

  • Now we need to create other send and receive adapter handlers for the WCF-SAP Adapter, to accomplished that we need to:
  • Expanded the adapter list, right-click the “WCF-SAP” adapter, point to New, and then:
    • click “Send Handler to create a send handler”
    • Or click “Receive Handler” to create a receive handler.

BizTalk-Administration-Console-Register-WCF-SAP-adapter-add-receive-send-handlers

Notice: that by default the adapter already have one Receive and one Send handler that are associated to the default Host Instance – normally the “BizTalkServerApplication” Host Instance

  • Add two send handler using Dedicated Send Hosts
    • One running under 32-bit: BizTalkServerSend32Host
    • One running under 64-bit: BizTalkServerSendHost
  • Add two receive handler using Dedicated Receive Hosts
    • One running under 32-bit: BizTalkServerSend32Host
    • One running under 64-bit: BizTalkServerSendHost
  • Delete the default handlers that use the “BizTalkServerApplication” Host (in my case it was “BizTalkServerApplication64Host”)

BizTalk-Administration-Console-Register-WCF-SAP-adapter-handler-configuration

Note: Now more about Create and Configure BizTalk Server Host and Host Instances in my TechNet Wiki article: BizTalk Server Best Practices: Create and Configure BizTalk Server Host and Host Instances

  • Finally we just need to restart our BizTalk Server Host Instances, for that you need to:
    • Expand the BizTalk group, click “Platform Settings”, and then click “Host Instances”.
    • In the details pane, right-click the host instance you want to start, and then click “Start”.

BizTalk-Administration-Console-restart-host-instances-final-step

Validate if the WCF-SAP adapter is properly installed

To do a preliminary test you to your WCF-SAP Adapter installation you can create a new receive port:

  • Right-click “Receive Ports”, point to “New”, and click “One-way Receive Port”

SAP-validation-add-new-receive-port

  • Just leave the default name and click on the “Receive Locations” tab and then click “New”.

SAP-validation-add-new-receive-location

  • In the Receive Location Properties dialog box, do the following:
    • From the Type drop-down list, select the “WCF-SAP” adapter you added earlier, and then click “Configure”.

SAP-validation-add-new-receive-port-configure-receive-location

If you were able to access the WCF-SAP Transport Properties window and the URI SAP configuration windows, this is half way thru and a good indication that the adapter is properly configured in your environment

WCF-SAP-Transport Properties-adn-URI-Windows

Of course now you need to actually test it against your SAP environment to see if you actually can receive or send messages from or to SAP System.

In my opinion there are a lack of documentation, or good documentation and many of the existing one is obsolete, regarding some topics/feature of BizTalk Server – Microsoft BizTalk Accelerator for RosettaNet is one of them.

Today while I was trying to extend Microsoft BizTalk 2013 Accelerator for RosettaNet (BTARN) with a new receive Partner Interface Process (PIP) schema I was receiving the following error in the event log:

Source module:
RNDisAssembler

Correlation information:

Description:
Receive pipeline rejected incoming message due to the following RNIF exception:
UNP.SCON.VALERR: A failure occurred while validating the service content.

Details:
The document specification <MyNamespace.MyPIP> from assembly <MyAssemblyName, Version=1.0.0.0, Culture=neutral, PublicKeyToken=…> failed to load. Verify the schema for this document specification is deployed and is in the Global Assembly Cache.

Note: this same error can occur in previous or new versions of BizTalk Server.

Based on the received error and according to a possible cause described by Microsoft at Troubleshooting: Microsoft BizTalk Accelerator for RosettaNet Issues and Resolutions either the document namespace or the root node property the deployed schema for the instance that you are trying to extend is incorrect.

In fact this could be the issue but I found really odd because in the error details my DLL, containing the schema that I was trying to extend, was being properly referenced, nevertheless I confirmed that it was properly deployed… But as I suspected this wasn’t my problem.

Note: this behavior does not happen with PIP that include out-of-the-box with BTARN (in the Microsoft.Solutions.BTARN.Schemas.RNPIPs dll) only with new ones and only in the incoming process.

Microsoft-Solutions-BTARN-Schemas-RNPIPs

Fortunately for us we have an extended BizTalk Server: List of Errors and Warnings, Causes, and Solutions at TechNet Wiki, I usually update with some frequency and that I used as a reference, which gave me some clues to the final solution. Nick Heppleston mention in his blog that:

“RN Disassembler does in-fact attempt to validate the message contained within the Service Content against a deployed schema just like the standard XmlDisassembler. The message that our trading partner was sending did not validate and hence the RosettaNet Accelerator threw this error message; once we had corrected the schema and redeployed, the error went away.

This is certainly one to be aware of if you are developing custom PIP’s to use with the RosettaNet Accelerator: ensure that the message in the Service Content validates against your custom PIP schema”

Again this isn’t my problem, because the Schema was properly deployed in the system, I only mention this because is important for understanding how the BTARN engine/processes works.

CAUSE

By default BTARN App Pool Settings are configured to use .NET framework 2.0, doesn’t enable 32-bit applications and the application pool is in Classic mode

BTARN-App-Pool-default-Settings

Important for you to know is that the accelerator requires both an in-process and out of process host, both of which must be marked as "Authentication Trusted" and "32-bit only".

To run the BTARN End to End scenario you need two important things:

  • Enable the BTARN Application Pools for 32 bit.
  • Add a HTTP Handler for *.dll refering the IsapiModule Filters.

But what I found today is that when you want to extend BTARN with new incoming PIP’s, the artifacts generated are going to be .NET 4.0/4.5 unless Visual Studio is configured to do otherwise, which we really cannot control using BizTalk projects:

re-targeting-Visual-Studio-BizTalk-Projects-error

This means along with setting the application pools for the 32-bit the .NET setting must be set to match.

SOLUTION

To solve this issue you must:

  • Type “Internet Information Services (IIS) Manager” or “IIS” in the Windows Start screen and click in “Internet Information Services (IIS) Manager” option on Apps menu.
  • Expand the server and click on “Application Pools” to display available application pools in center panel.
  • Right-click on “BTARNAppPool” and select “Advanced Settings”.
  • On the “Advanced Settings” window:
    • Change the value of “.NET Framework version” from “v2.0” to “v4.0”.
  • Change the value of “Enable 32-bit Applications” from “False” to “True”.
  • And then click “OK”.

BTARN-App-Pool-correct-Settings

Advice: you should do the same for the “BTARNHttpReceivePool” application pool

After I fix these configurations I was able to successfully receive the PIP message from my external Partner.

Credits to LemMotlo – BTARN App Pool Settings for BizTalk 2010

Last week while trying to generate from Visual Studio 2013 a schema of a custom SAP IDOC by:

  • Right-click your BizTalk Server project, and then choose “Add | Add Generated Items | Consume Adapter Service”.
  • In the “Consume Adapter Service” Add-in screen, select the sap adapter binding.
  • You should set the connection URI to SAP server and after that click “Connect
  • From the “Select contract type” drop-down list, select “Service (Inbound operations)” option
  • In the “Select a category” box, expand the IDOC node and select the IDOC that you want to retrieve, to see the IDOC message types in the “Available categories and operations” box.
  • From the “Available categories and operations”, add the “Receive” operation to the "Added categories and operations" by selecting the operation and click the “Add” button
  • And finally click “Ok” to generate the IDOC SAP schema

I got the following error:

“Error while retrieving or generating the WSDL. Adapter message: Details: ErrorCode=RFC_EXCEPTION. ErrorGroup=RFC_ERROR_APPLICATION_EXCEPTION. SapErrorMessage=SEGMENT_UNKNOWN. AdapterErrorMessage=Error returned by RfcCallReceiveEx while calling RFC: IDOCTYPE_READ_COMPLETE..

Microsoft.Adapters.SAP.RFCException: Details: ErrorCode=RFC_EXCEPTION. ErrorGroup=RFC_ERROR_APPLICATION_EXCEPTION. SapErrorMessage=SEGMENT_UNKNOWN. AdapterErrorMessage=Error returned by RfcCallReceiveEx while calling RFC: IDOCTYPE_READ_COMPLETE..”

Server stack trace:

at Microsoft.Adapters.SAP.RFCException.HelperThrow(Int32 retCode, String additionalErrorMessage)
at Microsoft.Adapters.SAP.RfcOutboundInvoker.Invoke()
at Microsoft.Adapters.SAP.InternalIdocMetadata..ctor(String idocType, String cimType, String release, String version, MetadataLookup metadataLookup, SAPConnection sapConnection, TimeoutHelper timeoutHelper)
at Microsoft.Adapters.SAP.SAPMetadataContract.ResolveTypeMetadata(String typeId, TimeSpan timeout, TypeMetadataCollection& extraTypeMetadataResolved)
at Microsoft.ServiceModel.Channels.Common.Design.MetadataCache.GetTypeMetadata(String uniqueId, Guid clientId, TimeSpan timeout)
at Microsoft.ServiceModel.Channels.Common.MetadataLookup.GetTypeDefinition(String typeId, TimeSpan timeout)
at Microsoft.Adapters.SAP.SapIdocMetadata..ctor(String absName, String idocType, String cimType, String release, String version, SAPConnection sapConnection, Boolean generateFlatFileCompatibleIdocSchema, Boolean segmentTypeInFlatFileAnnotation, MetadataLookup metadataLookup, TimeoutHelper timeoutHelper)
at Microsoft.Adapters.SAP.SAPMetadataContract.ResolveTypeMetadata(String typeId, TimeSpan timeout, TypeMetadataCollection& extraTypeMetadataResolved)
at Microsoft.ServiceModel.Channels.Common.Design.MetadataCache.GetTypeMetadata(String uniqueId, Guid clientId, TimeSpan timeout)
at Microsoft.ServiceModel.Channels.Common.MetadataLookup.GetTypeDefinition(String typeId, TimeSpan timeout)
at Microsoft.Adapters.SAP.IdocOperationMetadata.ExportXmlSchema(XmlSchemaExportContext schemaExportContext, MetadataLookup metadataLookup, TimeSpan timespan, OperationParameterDirection direction)
at Microsoft.Adapters.SAP.IdocOperationMetadata.ExportInputXmlSchema(XmlSchemaExportContext schemaExportContext, MetadataLookup metadataLookup, TimeSpan timespan)
at Microsoft.ServiceModel.Channels.Common.Design.WsdlBuilderHelper.AddOperationSchema(OperationMetadata operationMetadata, TimeSpan timeout)
at Microsoft.ServiceModel.Channels.Common.Design.WsdlBuilder.SearchBrowseNodes(MetadataRetrievalNode[] nodes, WsdlBuilderHelper helper, TimeoutHelper timeoutHelper)
at Microsoft.ServiceModel.Channels.Common.Design.WsdlBuilder.GenerateOperationSchemas(WsdlBuilderHelper helper, MetadataRetrievalNode[] nodes, TimeSpan timeout)
at Microsoft.ServiceModel.Channels.Common.Design.WsdlBuilder.GetWsdl(MetadataRetrievalNode[] nodes, Uri uri, TimeSpan timeout)
at Microsoft.Adapters.SAP.SapCustomWsdlRetrieval.GetWsdl(MetadataRetrievalNode[] nodes, Uri uri, TimeSpan timeout)
at Microsoft.ServiceModel.Channels.Common.Design.MetadataExchanger.ProcessMetadataGet(Message message, Uri target, TimeSpan timeout, MetadataLookup metadataLookup)
at Microsoft.ServiceModel.Channels.Common.Design.MetadataExchanger.ProcessMetadataMessage(Message message, Uri target, TimeSpan timeout, MetadataLookup metadataLookup, Message& replyMessage)
at Microsoft.ServiceModel.Channels.Common.Channels.AdapterRequestChannel.Request(Message message, TimeSpan timeout)
at System.ServiceModel.Dispatcher.RequestChannelBinder.Request(Message message, TimeSpan timeout)
at System.ServiceModel.Channels.ServiceChannel.Call(String action, Boolean oneway, ProxyOperationRuntime operation, Object[] ins, Object[] outs, TimeSpan timeout)
at System.ServiceModel.Channels.ServiceChannelProxy.InvokeService(IMethodCallMessage methodCall, ProxyOperationRuntime operation)
at System.ServiceModel.Channels.ServiceChannelProxy.Invoke(IMessage message)
Exception rethrown at [0]:
at System.Runtime.Remoting.Proxies.RealProxy.HandleReturnMessage(IMessage reqMsg, IMessage retMsg)
at System.Runtime.Remoting.Proxies.RealProxy.PrivateInvoke(MessageData& msgData, Int32 type)
at Microsoft.ServiceModel.Channels.IMetadataRetrievalContract.GetMetadata(MetadataRetrievalNode[] nodes)
at Microsoft.ServiceModel.Channels.Tools.MetadataSearchBrowse.MetadataPanel.GetWsdl(MetadataRetrievalNode[] nodes)
at Microsoft.ServiceModel.Channels.Tools.MetadataSearchBrowse.MetadataUserControl.GetWsdl()

BizTalk-Generating-SAP-schema-Error-while-retrieving-generating-WSDL

CAUSE

The SAP adapter uses the IDOCTYPE_READ_COMPLETE RFC to retrieve the metadata for the Receive operation for an IDOC. Invoking this RFC requires specific user permissions in the SAP system. To generate metadata, if you have connected to the SAP system using a credential that does not have permission to invoke the IDOCTYPE_READ_COMPLETE RFC, the SAP adapter gives an error.

So in order to demystify problems you should:

  • Make sure that your connection URI are well set
  • And you should try to import a schema from a standard IDOC, like INVOIC01, STATUS or ORDER01

If you are unable to import the schemas then you have a different problem from what I’m addressing here and you probably need to contact your SAP team to try to diagnose the problem, it probably may be lack of permissions. But normally in this cases you will receive a:

  • SapErrorMessage= OBJECT_UNKNOWN.

In my case I was able to import all the standard IDOC from SAP, however as I stated before I was trying to import the schema from a custom SAP IDOC created by my customer and I got instead a:

  • SapErrorMessage=SEGMENT_UNKNOWN

Which means, that while importing the IDOCTYPE_READ_COMPLETE RFC was not properly identifying some segments of the IDOC.

After validating with my SAP team we realize that some segments were not in the state “released” in SAP, this may not be the correct SAP interface logic but just to give you an idea here are some SAP print screens:

SAP-Set-release-custom-segment

Note: that all custom segments used in the IDOC must be released in SAP before you can import and use them in BizTalk Server.

SOLUTION

Well the only solution is to contact you SAP team and they must be sure that all segments of the IDOC that you are trying to import are released correctly.

Unfortunately we don’t have the segment information in question, but more likely it is some custom segment that they created.

After many requests and many postponements, due to my unavailability and free time to take these tasks, BizTalk Scheduled Task Adapter is finally officially available (version 5.0) and optimized for BizTalk Server 2013 R2!

You can download this new version of the adapter in BizTalk Scheduled Task Adapter CodePlex project page:

The BizTalk Scheduled Task Adapter is an in-process receive adapter that executes a prescribed task on a daily, weekly or monthly schedule. The adapter is configured entirely within BizTalk, all configurations is stored within the SSODB and can be exported and imported via binding files.
The schedule capabilities are similar to those available with the Windows Scheduled Task Service.

In this new version and despite additional custom tasks can be created and I’m planning on adding more, we still have the same four simple tasks present in previous editions:

  • XmlStringStreamProvider – generates a BizTalk message from a configured Xml string
  • FileStreamProvider – generates a BizTalk message from the contents of a file
  • HttpDownload – generates a BizTalk message from data downloaded from a web site
  • SQLStreamProvider – generates a BizTalk message from the contents of a SQL Query (similar to the old SQL adapter)

 

BizTalk Scheduled Task Adapter Release 5.0 for BizTalk Server 2013 R2

Requirements

The Scheduled Task Adapter v5.0 is optimized and designed to be used with BizTalk Server 2013 R2 (Compiled in .NET Framework 4.5).

V5.0 Change log

  • Compiled in Visual Studio 2013 and .NET Framework 4.5.
  • Optimized for BizTalk Server 2013 R2.
  • Support for 32 and 64 bit Host Instances.
  • Bug fixes
    • Bug: Issues multiple messages for timespan with more than 60 seconds – Solved

BizTalk-Server-2013-R2-BizTalk-Scheduled-Task-Adapter-v5.0-timespan

    • Bug: XmlStringStreamProvider task page properties not showing XML Text Editor Box – Solved
    • Bug: FileStreamProvider task page properties not showing Open File Dialog Box – Solved
    • Bug: SQLStreamProvider task page properties not showing Data Link properties Box to easy configure the SQL Connection string – Solved
    • Bug: Find task window showing all task components disabled – Solved
  • Improvements
    • SQLStreamProvider task now enables you to define SQL Timeout property – credits to MACoronado
    • Tasks Properties are now better organized and with better descriptions

BizTalk-Server-2013-R2-BizTalk-Scheduled-Task-Adapter-v5.0

Release History

This adapter is available since BizTalk Server 2004.

  • Release 5.0: release in February 18 2015 by Sandro Pereira, this adapter was tested to work on BizTalk Server 2013 R2. Compiled in .NET Framework 4.5
  • Release 4.0: release in June 12 2012 by Sandro Pereira, this adapter was tested to work on BizTalk Server 2010. Compiled in .NET Framework 4.0
  • Release 3.0: release in Aug 10 2010 by Greg Forsythe, this adapter was tested to work on BizTalk Server 2009. Compiled in .NET Framework 2.0
  • Release 2.0: last release in Apr 20 2008 by Greg Forsythe, this adapter works with BizTalk Server 2006 and BizTalk Server 2006 R2. Compiled in .NET Framework 2.0
  • Release 1.02: last release in Apr 20 2008 by Greg Forsythe, this adapter works with BizTalk Server 2004, BizTalk Server 2006 and BizTalk Server 2006 R2. Compiled in .NET Framework 1.1

 

Download

You can download this new version of the adapter in BizTalk Scheduled Task Adapter CodePlex project page:

A few days ago I wrote a post about these same warning messages from WCF-SAP Adapter: The adapter "WCF-SAP" raised an error message. Details "System.ServiceModel.CommunicationObjectFaultedException: The communication object, Microsoft.Adapters.Internal.LayeredChannelBindingElement.LayeredInboundChannel cannot be used for communication because it is in the Faulted state.

The adapter "WCF-SAP" raised an error message. Details "Microsoft.Adapters.SAP.RFCException: Details: ErrorCode=RFC_INVALID_HANDLE. AdapterErrorMessage=An exception has occurred on the listener while executing RfcWaitForRequest..

The adapter "WCF-SAP" raised an error message. Details "The WCF service host at address "sap://CLIENT=[SAPClientID];LANG=[LANG];@A/[SAPServer]/[SystemID]?ListenerGwServ=[GWServer]&ListenerGwHost=[GwHost]&ListenerProgramId=[ProgID]&RfcSdkTrace=True&AbapDebug=False" has faulted and as a result no more messages can be received on the corresponding receive location. To fix the issue, BizTalk Server will automatically attempt to restart the service host."

The adapter "WCF-SAP" raised an error message. Details "System.ServiceModel.CommunicationObjectFaultedException: The communication object, Microsoft.Adapters.Internal.LayeredChannelBindingElement.LayeredInboundChannel`1[System.ServiceModel.Channels.IReplyChannel], cannot be used for communication because it is in the Faulted state.

I told at the time that this are generic error messages and does not provide what is really the problem.

These warnings occurs, normally, when BizTalk is trying to connect to a SAP system to receive the IDOC and, again, most of the times these are related with connectivity issue or permissions between BizTalk and SAP.

CAUSE

Normally, the reason for these warnings could be any of the following options:

  • There may be a problem with the SAP system.
  • Maybe BizTalk Server don’t have the proper authorization to connect with that particular SAP program id
    • Check my previous post here
  • Also some times is a configuration problem in the Receive Location in your BizTalk Server

There are some options for you to try to find more details about this warnings:

  • You can use external tools, like Wireshark, to dig deep into network traffic and inspect individual packets for clues
  • You may enable the RfcSdkTrace in the WCF-SAP port configuration to be able to see all the traces.
  • Or another useful option is to setup WCF tracing to see the underlying error.

But what I realized today is that sometimes this warnings may occur and none of the assumptions described above fit into the actual problem.

While I was migrating and configuring one BizTalk solution, I forgot to start the incoming IDOC subscriber (in this case an orchestration) which caused my messages to stay Suspended in a Non-resumable way, raising a “no subscribers were found” error

The Messaging engine failed to process a message submitted by adapter:WCF-SAP Source URL: sap://CLIENT=[SAPClientID];LANG=[LANG];@A/[SAPServer]/[SystemID]?ListenerGwServ=[GWServer]&ListenerGwHost=[GwHost]&ListenerProgramId=[ProgID]&RfcSdkTrace=True&AbapDebug=False. Details: The published message could not be routed because no subscribers were found. This error occurs if the subscribing orchestration or send port has not been enlisted, or if some of the message properties necessary for subscription evaluation have not been promoted. Please use the Biztalk Administration console to troubleshoot this failure.

And as you can see in the print screen bellow this error will generate also the appearance of the WCF-SAP warnings in the event viewer… although there is no problem in connectivity between BizTalk and SAP, and all the messages (IDOC) are being received and reached BizTalk

BizTalk-Server-2013-R2-WCF-SAP-Warnings-Event-Viewer-why

SOLUTION

In this particular case the solution is really simple, just create, or set correctly, one subscribe (Orchestration or send port with a filter) for the incoming IDOCs.

Is nothing new that in the last weeks I been busy performing BizTalk projects migrations from BizTalk Server 2006 R2 to 2013 R2 and, unintentionally, it seems that I can pick up and detect all the “bugs”, problems or limitations that you might imagine… or not. The good news is that I have several topics to write about it in my blog, as you may have noticed by my recent posts.

As a BizTalk Developer when you create a new BizTalk Solution, or open an existing one, you are used to have the BizTalk solution deploy option, of course in your development environment, which will allow you to easily deploy the entire BizTalk Solution directly from Visual Studio to your BizTalk Server runtime:

BizTalk-Server-2013-R2-Visual-Studio-2013-Deploy-Solution

During these weeks I notice that when I migrated an old BizTalk Solution from Visual Studio 2005 (BizTalk Server 2006 R2 Solution) to Visual Studio 2013 (BizTalk Server 2013 R2 Solution), I will soon talk about this topic in my blog – project migration, I realized that the “Deploy Solution” option did not appear in the context menu of my Visual Studio Solution:

BizTalk-Server-2013-R2-Visual-Studio-2013-without-Deploy-Solution

CAUSE

Visual Studio allow you to store different configurations of solution and project properties to use in different kinds of builds. To create, select, modify, or delete a configuration, you can use the Configuration Manager option present in the solution context menu.

A solution configuration specifies how projects in the solution are to be built and deployed. And by default when you create a new BizTalk Solution, or add a new BizTalk project to an existent solution, the “Build” and “Deploy” options are selected for the new project.

BizTalk-Server-2013-R2-Visual-Studio-2013-solution-configuration

However, sometimes when we update (migrate) an old Visual Studio Solution to a newer one, in this case Visual Studio 2005 to Visual Studio 2013, some of this configurations may disappear, or may not be present. The curious thing is that:

  • if the “Build” option is not select in the solution configuration, the “Build Solution” option continues to appear in the solution context menu, but it does do anything;
  • But if the “Deploy” option is not select in the solution configuration, the “Deploy Solution” doesn’t appear in the solution context menu;

BizTalk-Server-2013-R2-Visual-Studio-2013-solution-Configuration-Manager

SOLUTION

To solve this problem you must select the Deploy option in your solution configuration, for that you must:

  • In Visual Studio, right-click in your BizTalk Solution and select “Configuration Manager…” option from the context menu

BizTalk-Server-2013-R2-Visual-Studio-2013-solution-Configuration-Manager-option

  • On the “Configuration Manager” window, in the “Project contexts” pane, for every project, select the Configuration and Platform you want, and select whether to Build it and whether to Deploy it.
    • In this case make sure that “Deploy” is selected

BizTalk-Server-2013-R2-Visual-Studio-2013-solution-Configuration-Manager-deploy-option

Right-click in your BizTalk Solution and the “Deploy Solution” will now be available.

BizTalk-Server-2013-R2-Visual-Studio-2013-Deploy-Solution-final

In the last few weeks I have been playing around with WCF-SAP adapter, I have many thing to write about it in terms of installation, configuration, communication and so on but I will start with this topic/problem.

While trying to create a WCF-SAP Receive port to be able to listener incoming IDOC from SAP system and despite the receive location be and stay enable in the BizTalk Administration Console I soon realized that the documents were not being picked up by BizTalk.

When I consulted the Event Viewer to check if there were additional information about the causes that were happening I found this three warning messages:

“The adapter "WCF-SAP" raised an error message. Details "System.ServiceModel.CommunicationObjectFaultedException: The communication object, Microsoft.Adapters.Internal.LayeredChannelBindingElement.LayeredInboundChannel`1[System.ServiceModel.Channels.IReplyChannel], cannot be used for communication because it is in the Faulted state.
at System.ServiceModel.Channels.CommunicationObject.Close(TimeSpan timeout)
at System.ServiceModel.Channels.CommunicationObject.Close()
at System.ServiceModel.Dispatcher.ErrorHandlingReceiver.Close()".

“The adapter "WCF-SAP" raised an error message. Details "The WCF service host at address "sap://CLIENT=[SAPClientID];LANG=[LANG];@A/[SAPServer]/[SystemID]?ListenerGwServ=[GWServer]&ListenerGwHost=[GwHost]&ListenerProgramId=[ProgID]&RfcSdkTrace=True&AbapDebug=False" has faulted and as a result no more messages can be received on the corresponding receive location. To fix the issue, BizTalk Server will automatically attempt to restart the service host."

“The adapter "WCF-SAP" raised an error message. Details "Microsoft.Adapters.SAP.RFCException: Details: ErrorCode=RFC_FAILURE. AdapterErrorMessage=An exception has occurred on the listener while executing RfcWaitForRequest..
at Microsoft.ServiceModel.Channels.Common.Design.AdapterAsyncResult.End()
at Microsoft.ServiceModel.Channels.Common.Channels.AdapterReplyChannel.EndTryReceiveRequest(IAsyncResult result, RequestContext& requestContext)
at Microsoft.Adapters.Internal.LayeredChannelBindingElement.LayeredInboundChannel`1.
System.ServiceModel.Channels.IReplyChannel.EndTryReceiveRequest(IAsyncResult result, RequestContext& context)
at System.ServiceModel.Dispatcher.ReplyChannelBinder.EndTryReceive(IAsyncResult result, RequestContext& requestContext)”

BizTalk-WCF-SAP-Adapter-Event-Viewer-warnings

CAUSE

Well. unfortunately this errors are generic error messages and does not provide what is really the problem.

So my advice is to first check all the port configurations for any possible configuration mistakes. After that you should use external network tools that let you dig deep into network traffic and inspect individual packets, for example Wireshark.

On this particular case I found that the BizTalk Server didn’t have the proper authorization to connect with that particular SAP program id:

ERR*.1.registration of tp [PROGRAM ID] from host [BIZTALK SERVER] not allowed.720.SAP-Gateway.721.2.gwxxrd.c.3644..Thu Feb  5 18:46:11 2015….33844.SAP-Gateway on host [SAP SERVER] / [GWServer]…..*ERR*.

BizTalk-WCF-SAP-Adapter-wireshark-monitoring

SOLUTION

Unfortunately, I’m not a SAP expert and I don’t know exactly what to do in SAP, what I can tell you is that there is nothing wrong in your configuration, this is not a BizTalk problem Smile. What I could see in one of the SAP tools was that BizTalk was trying to connect but it was straight away disconnected.

So to solve this problem you must contact your SAP team to proper configure the access. Once is done everything will work fine, at least in this case it solved my problems.

Back again to one of my favorites topics: transformations. This is something that several people asked me for help in the past but I never found time to reply… until now.

A quite note: if you want to know more about BizTalk Maps transformation check out my free book available at BizTalk360 website: BizTalk Mapping Patterns & Best Practices

While migrating an older BizTalk Map transformation, from a custom schema to a SAP IDOC schema, from an entire custom XSLT file to BizTalk Mapper (don’t get me wrong, I only made this migration because the source schema changed so I had the need to change the entire XSLT code, otherwise I would have used the existing external file), I had the need to implement some part of the transformation in an Inline XSLT code (using a Scripting Functoid) and I only used inline XSLT because I was transforming a flat structure from the source schema to a recursive node in the target schema base on some conditions (otherwise I would have used the Table Lopping Functoid)

BizTalk-Mapper-inline-scriptin-functoid-with-prefix

<ns1:E2EDKA1003>
  <ns1:DATAHEADERCOLUMN_SEGNAM>E2EDKA1003</ns1:DATAHEADERCOLUMN_SEGNAM>
  <ns1:PARVW>LF</ns1:PARVW>
  <ns1:PARTN>0000100000</ns1:PARTN>
</ns1:E2EDKA1003>

<ns1:E2EDKA1003>
  <ns1:DATAHEADERCOLUMN_SEGNAM>E2EDKA1003</ns1:DATAHEADERCOLUMN_SEGNAM>
  <ns1:PARVW>ZC</ns1:PARVW>
  <ns1:PARTN>
    <xsl:choose>
      <xsl:when test="@Transportation='1'">
        <xsl:value-of select="'0000100001'" />
      </xsl:when>
      <xsl:otherwise>
        <xsl:value-of select="'0000100009'" />
      </xsl:otherwise>
    </xsl:choose>
  </ns1:PARTN>
</ns1:E2EDKA1003>

Note that I’m using the prefix “ns1” on the element because the schemas is expecting that, and it should work because both the schema and the transformation file (XSL) contains the namespace

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
     xmlns:msxsl="urn:schemas-microsoft-com:xslt" 
     …
     xmlns:s1="http://unicer.pt/OrderUnigest01.xsd"
     xmlns:ns1="http://Microsoft.LobServices.Sap/2007/03/Types/Idoc/3/ORDERS01//700"
     xmlns:userCSharp="http://schemas.microsoft.com/BizTalk/2003/userCSharp">

BizTalk-Mapper-xslt-prefix-namespace

You can validate that by:

However, when you either compile the map or validate it, we get the following error message:

Validate the map or compile it, I get the following error:

Exception Caught: ‘ns1′ is an undeclared prefix. Line …, position …

 

CAUSE

Well unfortunately BizTalk Mapper Editor doesn’t like prefixes in inline XSLT code, although they exist he is not able to understand them without additional information in the code, which makes our work a little more difficult or we need to use a different strategy in our XSLT code.

Luckily, we can easily fix this strange behavior of the editor.

SOLUTION

The cleanest way to solve this strange behavior is to use the <xsl:element> element or <xsl:attribute> element to create the records, elements and attributes required, instead of manually create them <ns1:E2EDKA1003></ns1:E2EDKA1003> without the <xsl:element> element:

<xsl:element name="ns1:E2EDKA1003">
  <xsl:element name="ns1:DATAHEADERCOLUMN_SEGNAM">E2EDKA1003</xsl:element>
  <xsl:element name="ns1:PARVW">LF</xsl:element>
  <xsl:element name="ns1:PARTN">0000100000</xsl:element>
</xsl:element>

<xsl:element name="ns1:E2EDKA1003">
  <xsl:element name="ns1:DATAHEADERCOLUMN_SEGNAM">E2EDKA1003</xsl:element>
  <xsl:element name="ns1:PARVW">ZC</xsl:element>
  <xsl:element name="ns1:PARTN">
    <xsl:choose>
      <xsl:when test="@Transportation='1'">
        <xsl:value-of select="'0000100001'" />
      </xsl:when>
      <xsl:otherwise>
        <xsl:value-of select="'0000100009'" />
      </xsl:otherwise>
    </xsl:choose>
  </xsl:element>
</xsl:element>

If you don’t want to use the <xsl:element> element or <xsl:attribute> element, then you need to declare the prefix namespace in the record:

<ns1:E2EDKA1003 xmlns:ns1="http://Microsoft.LobServices.Sap/2007/03/Types/Idoc/3/ORDERS01//700">
  <ns1:DATAHEADERCOLUMN_SEGNAM>E2EDKA1003</ns1:DATAHEADERCOLUMN_SEGNAM>
  <ns1:PARVW>LF</ns1:PARVW>
  <ns1:PARTN>0000100000</ns1:PARTN>
</ns1:E2EDKA1003>

<ns1:E2EDKA1003 xmlns:ns1="http://Microsoft.LobServices.Sap/2007/03/Types/Idoc/3/ORDERS01//700">
  <ns1:DATAHEADERCOLUMN_SEGNAM>E2EDKA1003</ns1:DATAHEADERCOLUMN_SEGNAM>
  <ns1:PARVW>ZC</ns1:PARVW>
  <ns1:PARTN>
    <xsl:choose>
      <xsl:when test="@Transportation='1'">
        <xsl:value-of select="'0000100001'" />
      </xsl:when>
      <xsl:otherwise>
        <xsl:value-of select="'0000100009'" />
      </xsl:otherwise>
    </xsl:choose>
  </ns1:PARTN>
</ns1:E2EDKA1003>

In any of the case that you decide to implement, if then you try to compile or validate the map, everything will work fine and the error will disappear.

Here’s a topic that, without any particular reason, I never or I rarely addressed in my blog: Business Rules Engine (BRE)

The goal of this post is not to explain BRE but since it’s the first time that I cover something related with this topic, let’s first make a small introduction and share some notes and personal opinions about it.

Business Rules Engine (BRE)

Business Rules Engine (BRE) is a run-time inference engine that can link highly readable, declarative, semantically rich rules to any business objects (.NET components), XML documents, or database tables. It can evaluates rules against facts and initiates actions based on the results of that evaluation. This an optional component that comes out-of-the-box with BizTalk Server that enable you to directly create, modify and isolate a sets of rules of business decisions (business rules). To be more accurate, since BizTalk Server 2004 version, Microsoft has introduced in the product the Business Rules Framework, a stand-alone application that consists of a number of modules, support components, and tools. The primary modules includes:

  • Business Rule Composer, a graphical user interface that enables developers, business analysts and administrators for constructing vocabularies and policies;
  • Rule Engine Deployment Wizard for export, import, deploy or undeploy vocabularies and/or policies created in the Business Rule Composer;
  • And the Run-Time Business Rule Engine that executes policies on behalf of a host application.

However, and in my opinion, this is the second BizTalk Server most misunderstood component only outweighed by BAM (Business Activity Monitoring). And one of the reasons “why?” Is that, Business Rule Composer is a tool initially designed for Business Analysts, or those responsible for the business, to create and update Business Rules at any time without affecting the code implemented by the developer team. In this perspective, or initial intention, the BizTalk Developer is not responsible to create Business Rules, because in reality he will often be unfamiliar with the business, but he will be able to use or reuse them (BR) in their orchestrations to support a variety of scenarios like: determine the execution path of a business process.

BRE-Business-Rules-Engine-Overview

But one of the problems is that Business Rule Composer is a tool unfriendly, or too complex, for Business Analysts, which forces:

  • The Developers to stay with the task of creating them
  • And to the Administrators to maintain them

With an unfamiliar tool (Developer are familiar with Visual Studio and Administrators with BizTalk Administration Console) and sometimes with unfamiliar terms (vocabularies, rules and policies) to accomplish that.

Despite this component has not suffer any radical changes since 2004, BRE is still a powerful feature in BizTalk Server and you can make amazing thing with it. Ricardo Torre mentioned in his series about BizTalk Server Tips that:

  • Business Rule Engine is a high performance engine to evaluate business rules even when compared with WF Rules
  • And that Business Rule Engine is a good way of to modularize the constantly changing business logic that is often developed inside Orchestrations, making changes a more smooth process since updating a policy to the latest version doesn’t require any downtime at all.

In fact the most common application of BRE is to isolate business rule, in a centralized manner, from the BizTalk applications making it eminently reusable in a simple and efficient manner. But what many people don’t realize is that we can do many more things with it, for example:

  • BRE can be used to store configuration data (or Application configurations), using a vocabulary, which is essentially parameters, or friendly names for the facts, that can be used within the execution of a rules policy. However the vocabularies can also be accessed from C# code and they can be a wonderful way to abstract facts from their implementation.
    • The Rule Engine Config Get Functoid, available in the BizTalk Mapper Extensions UtilityPack, allows you to obtain a definition value from a Vocabulary in the Business Rules Engine to be used inside your maps.

Before we went to the purpose of this post let me mention a particular note: Normally we have policies that consumes vocabularies to generate rules, however:

  • We can have simple vocabularies that are not consumed by any policy
  • Or we can have simple policies that doesn’t consume any vocabulary

This week I have the necessary to migrate a simple policy (without any vocabulary) from an old version of BizTalk (2006 R2) to BizTalk Server 2013 R2. So what is necessary to migrate this artifacts’? Do I need to recreate everything or are they compatible?

How to migrate Business Rules Policies from BizTalk Server 2006/2006 R2 to BizTalk Server 2013 R2

Well, as I mentioned earlier in this post, BRE doesn’t suffer any radical changes since 2004 therefore this is a very simple task to be accomplished. For that you just only need to use the Rules Engine Deployment Wizard tool to import from your older environment and export them into your new environment.

Exporting policy from BizTalk Server 2006/2006 R2:
  • Click “Start”, “Programs”, “Microsoft BizTalk Server 2006”, and then click “Business Rules Engine Deployment Wizard”.

01-BTS2006-Business-Rules-Engine-Deployment-Wizard

  • On the “Welcome to the Rules Engine Deployment Wizard” page, click “Next”.

02-BTS2006-Business-Rules-Engine-Deployment-Wizard-Welcome

  • On the “Deployment Task” page, select “Export Policy/Vocabulary to file from database” option, and then click “Next”.

03-BTS2006-Business-Rules-Engine-Deployment-Wizard-Deployment-Task

  • On the “Policy Store” page, from the drop-down lists, select an available SQL Server computer and database, and then click “Next”.

04-BTS2006-Business-Rules-Engine-Deployment-Wizard-Policy-store

  • On the “Export Policy/Vocabulary” page:
    • Select “Policy” option.
    • From the Policy/Vocabulary drop-down list, select the desired policy you want to export.
    • Click “Browse” to select the definition file path and name.
    • And then click “Next “

05-BTS2006-Business-Rules-Engine-Deployment-Wizard-Export-Policy-Vocabulary

  • On the “Ready” page, review the information, and then click “Next”.

06-BTS2006-Business-Rules-Engine-Deployment-Wizard-Ready

  • On the “Exporting Policy/Vocabulary” page, after export is completed, click “Next”.

07-BTS2006-Business-Rules-Engine-Deployment-Wizard-Exporting-Policy-Vocabulary

  • On the “Completing the Rules Engine Deployment Wizard” page, review the completion status, and then click “Finish”.

08-BTS2006-Business-Rules-Engine-Deployment-Wizard-complete

Importing policy to BizTalk Server 2013 R2:
  • In the BizTalk Server machine, press the “Windows key” to switch to the Start screen, type “Business Rules Engine Deployment Wizard” or “rules”, and then click “Business Rules Engine Deployment Wizard” option from the Search menu.

09-BTS2013R2-Business-Rules-Engine-Deployment-Wizard

  • On the “Welcome to the Rules Engine Deployment Wizard” page, click “Next”.

10-BTS2013R2-Business-Rules-Engine-Deployment-Wizard-Welcome

  • On the “Deployment Task” page, select “Import and publish Policy/Vocabulary to database from file” option, and then click “Next”.

11-BTS2013R2-Business-Rules-Engine-Deployment-Wizard-Deployment-Task

  • On the “Policy Store” page, from the drop-down lists, select an available SQL Server computer and database, and then click “Next”.

12-BTS2013R2-Business-Rules-Engine-Deployment-Wizard-Policy-store

  • On the “Import Rules Engine Policy/Vocabulary file” page:
    • Click “Browse” to select the definition file that we previous export from BizTalk Server 2006/2006 R2.
    • And then click “Next “

13-BTS2013R2-Business-Rules-Engine-Deployment-Wizard-Import-Policy-Vocabulary-file

  • On the “Ready” page, review the information, and then click “Next”.

14-BTS2013R2-Business-Rules-Engine-Deployment-Wizard-Ready

  • On the “Importing Policy/Vocabulary” page, after import is completed, click “Next”.

15-BTS2013R2-Business-Rules-Engine-Deployment-Wizard-Importing-Policy-Vocabulary

  • On the “Completing the Rules Engine Deployment Wizard” page, review the completion status, and then click “Finish”.

16-BTS2013R2-Business-Rules-Engine-Deployment-Wizard-complete

Now if we access to the Business Rule Composer you will notice that your policy is published are ready to be deployed.

17-BTS2013R2-Business-Rules-Composer

I’m not much of a historian and I don’t read too many history books but from what I can remember from my school days… (please be open mind and do not think I’m completely crazy…the story will have a context and meaning at the end)

The Story

A few hundred years ago many cultures around the world still believe that the planet Earth was flat disk or a square, rather than a sphere, at the edge there were infinite length cliffs straight down into the darkest depths.

Myths of the age of discovery, where the Portuguese ships, then Spanish, were the first to set sail to discover a world, leaving the coastal waters of the Old World and embarked on their adventure on the vast "green sea of darkness said that Europe sat in the middle of the circle, with the other continents scattered about the fringes, and parts of Africa hanging over the edge and the oceans lapped against the sides of the Earth, and in places ran over, creating currents that would pull over the edge ships that ventured too far out to sea.

End-of-the-world-sailor

Luís de Camões, considered the Portuguese language’s greatest poet, has created a mythical figure: the giant Adamastor (Northwind), as a symbol of the forces of nature Portuguese navigators had to overcome during their discoveries and more specifically of the dangers Portuguese sailors faced when trying to round the Cape of Storms, in Africa and supposedly one of the edge of the earth. A giant creature that appears to them, walking in the depth of the sea; his head reaches to the clouds; the storms, the winds, the thunders, and the lightning’s hang about him; his arms are extended over the waves.

The-Giant-Adamastor

It seems once again that a Portuguese sailor (me) found the giant Adamastor… this time inside BizTalk Mapper Editor! Tormenting me and not letting me go further and my FunctoIds vanished into the hell darkest depths.

PROBLEM (the story meaning and context)

Over the last weeks I’ve been busy performing BizTalk projects migrations from BizTalk Server 2006 R2 to 2013 R2 and, unintentionally, it seems that I can pick up and detect all the “bugs”, problems or limitations that you might imagine… or not, this is one of the case. The problem that I faced today it is the most crazy behavior that I found in the BizTalk Mapper Editor, and made me remember this story and that I reached and went over to the edge of “flat Earth”, in this case to the end of the grid page world!

In a global picture: migrating a map is straightforward and quite simple operation, there is no rock science behind it! Most of the times you don’t need to touch them, they are compatible.

However it was a big surprise to me, when I was in the process of optimizing one of the maps, I found out in one of the grid pages that I could not reach, and even see, some of the FunctoIds present, although I was able to see their existence through the links in the grid page

BizTalk-Mapper-grid-overview.bottom

I know what you may think… zoom out the grid and/or collapse the tree view… nothing!

BizTalk-Mapper-grid-overview.bottom-zoom-out

Ok… check the “Grid preview”… still nothing!

BizTalk-Mapper-grid-overview.bottom-grid-preview

Believe me I try everything that I could remember including restart Visual Studio and so on…

So, just to be sure that I wasn’t insane, I went to Visual Studio 2005 to open the BizTalk Server 2006 R2 version of the project, to check what was in that particular part of the grid page and voilà… I found 6 FunctoIds that were making conditional transformations

BizTalk-Mapper-2006-grid-overview-bottom

CAUSE - So, where are my FunctoIds in the grip page?

Before I explain the problem and the solution (or workaround) I like to say that this is not a runtime bug, which means, if I had deploy this map to my BizTalk environment everything would work fine. Instead this is a “bug”/”limitation” of the BizTalk Server SDK, that will turn your life into hell, it will drive you crazy, if you’d like to change that part of the map.

What I found out is that the configurations of working area (space) of the grid page, at least since BizTalk Server 2013, have changed. Now the working are of the grid page is in a square format and previous it has in a rectangle format, as you can see below:

BizTalk-Mapper-grid-page-workplace

Despite this change, I never thought that this would affect the development and maintenance of my maps… but it affects!

SOLUTION (workaround)

When I check the old version of the project inside Visual Studio 2005, I realize that the FunctoIds that I was trying to reach were at the bottom right corner at the very end of the working area of the grid page, with a large space gap for the remaining FunctoIds present in the middle of the grid page working area

BizTalk-Mapper-2006-grid-overview-right-bottom

To solved this problem I dragged the FunctoIds from the bottom right corner into the middle of the grid page working area, narrowing down the space gap between them, but most important, placing all the FunctoIds near the center of grid page working area:

BizTalk-Mapper-2006-grid-overview-middle

Then you just need to save this version of the map (Visual Studio 2005), take the “.btm” file and you only need to overlay this map to the existing one in your Visual Studio 2013/BizTalk Server 2013 R2 solution.

BizTalk-Mapper-2013-R2-Visual_Studio-2103-grid-overview

Finally my FunctoIds are visible! And once again the giant Adamastor was defeated.