Wade Wegner

I’ve started working on a project that integrates into Great Plains 9.0 using eConnect.  Not having done this using BizTalk Server 2006, I thought I’d document some of my observations and the steps I took.

To begin, I was able to get eConnect for GP (en_econnect_for_gp.zip) through my MSDN subscription.  If you have Great Plains 9.0, then you should be able to get your hands on this package.  When you unzip the package, you’ll notice two files:

• eConnectInstallAdminGuide.pdf – This is a great document that, if you are going to interact and develop with eConnect, I highly encourage you to read.  There are three parts: eConnect Basics, Installation, and Administration.  At the very least, developers should reach the first part, which includes an overview and architecture chapter.
• Microsoft_Business_Solutions_eConnect.msi – This is the actual installation file.  Note: it contains MUCH more than just the BizTalk Server adapters.

After reading through the eConnect guide, I ran the installation MSI file.  A few highlights / comments:

• I chose the “Custom” setup.  I never choose Standard or Complete.
• My sole purpose at this point is to install the BizTalk adapter with the eConnect schemas; follow the administration guide, instead of this post, if you’re setting up for production.
• There are a lot of features, including:
  • BizTalk Components – both 2004 and 2006
  • Business Objects – installs the Business Objects into SQL Server
  • COM+ Components – installs COM components and .NET assemblies
  • eConnect Incoming Service – incoming eConnect Win32 service
  • eConnect Outgoing Service – outgoing eConnect Win32 service
  • eConnect Replication Service – eConnect Win32 replication service
  • eConnect Help – help
  • eConnect Samples – .NET and VB6 examples
  • Queue Control – view documents in MSMQ queue
  • Schemas – eConnect XSD and XDR schemas
• Not knowing any better, I decided to only include the following features:
  • BizTalk Components
  • eConnect Help
  • eConnect Samples
  • Schemas

Once you have installed eConnect 9.0, you must still install the adapters for BizTalk Server.  Browser to the following folder: C:\Program Files\Microsoft Great Plains\eConnect9\BizTalk\BizTalk 2006\ (obviously, choose \BizTalk 2004\ if  you are using 2004).  From here you can run the BTS_eConnectAdapter.msi file and install the BizTalk Server 2006 adapter.

Once the installation for the adapter is complete, make sure you update your platform settings and add the adapter.  Follow these steps:

1. Open the BizTalk Server 2006 Administration Console.
2. Go to BizTalk Group -> Platform Settings -> Adapters.
3. Right-click the Adapters folder, and select New -> Adapter.
4. Enter a name for the adapter (e.g. eConnect) and select the “Dynamics GP eConnect” adapter from the adapter list.
5. Click OK.  Make sure you restart your host instances.

Pretty simple and straightforward.

Now, browse to the following folder: C:\Program Files\Microsoft Great Plains\eConnect9\XML Schemas\.  Here you will notice all the XDR and XSD schemas.  In particular, the “Incoming XSD Individual Schemas” and the “Incoming XSD Schemas” folders.  The first has every schema in an individual XSD, whereas the second has them all in an eConnect.xsd file.  Depending on you circumstances, you can import these schemas into your BizTalk projects, so that you can utilize them in Orchestrations, maps, or whatever else you choose.  Additionally, once you deploy your projects assemblies, the schemas will be available within your BizTalk solution.

And finally, one other folder you may want to look at is C:\Program Files\Microsoft Great Plains\eConnect9\XML Sample Documents\Incoming\.  This folder has a number of sample XML documents that you can use for testing.  VERY useful stuff here!

Just a few things I’ve learned and observed while getting all this configured.  I’m sure I’ll post more as I continue to use the eConnect adapter.

I hope this helps!

I just recently started a new BizTalk Server 2006 project in which I created a custom pipeline component to assist in the compression and decompression of messages.  The plan is to have a receive location monitor a folder via the File adapter, and when a zip file is uploaded via FTP from a 3rrd party process, the receive location will use the custom pipeline component , via a receive pipeline, to decompress the file and publish the message to the MessageBox.  Pretty slick!

See the WingtipToys solution in the SDK folder for a great heads-start to creating a compression / decompression pipeline component.  You can find this solution in the following folder: C:\Program Files\Microsoft BizTalk Server 2006\SDK\Scenarios\PM\.

So, to get this rolling, I added a C# project to my BizTalk solution.  There are few things I configure on these C# library projects, as I need to utilize the output assembly in my Pipelines BizTalk project.

1. Set the build output path to the following location (for the Debug configuration): C:\Program Files\Microsoft BizTalk Server 2006\Pipeline Components\.  This way, every time the project is built, the debug assembly is placed in the Pipeline Components folder.  From here, you can then reference the pipeline component appropriate through both Visual Studio 2005 (for your receive pipeline) and when you deploy it to BizTalk Server.
2. Uncheck the “Build” checkbox, for the C# library project, in the Solution Configuration.  This way, when you rebuild or deploy the solution, the C# library project isn’t also rebuilt.  The reason is that you will most likely get errors or warnings indicating that the file is in use, and cannot be rebuilt.  This is fine – you can simply do this manually.

Having made these changes, you now have a pretty flexible setup for moving forward.

When you reference the custom pipeline component assembly, you’ll want to reference the assembly that has been built in the C:\Program Files\Microsoft BizTalk Server 2006\Pipeline Components\ folder.  This way, when you deploy your receive or send pipelines, BizTalk will continue to reference the same assembly.

However, having referenced this assembly, you will see these warnings the next time you build your solution:

—— Build started: Project: BizTalkApp, Configuration: Development .NET ——
Updating references…
The dependency ‘Microsoft.BizTalk.Tracing’ could not be found.
The dependency ‘Microsoft.BizTalk.Bam.EventObservation’ could not be found.
The dependency ‘Microsoft.BizTalk.Streaming’ could not be found.
The dependency ‘Microsoft.BizTalk.XPathReader’ could not be found.
Performing main compilation…

While these warnings are harmless, they are annoying.  In order to “suppress” these warnings, select the referenced custom pipeline component assembly, and set Copy Local from True to False.  Once you do this, these warnings will disappear.

I hope this helps!

The Commerce Server team has released four white papers outlining how to use the Commerce Server adapters to export a product catalog, export an inventory catalog, export new orders, and export user profiles.  If you are attempting to use the adapters (or even thinking about it), I highly encourage you to take a look at these white papers.  If nothing else, they will give you a good overview of how you can make use of these adapter (I’ve been wanting to blog on them for awhile now, but haven’t found the time).

• Using Commerce Server 2007 Catalog Adapter

In this lab, you will use the Microsoft Commerce Server 2007 Catalog adapter with Microsoft BizTalk Server 2006 to export a catalog from the Commerce Server 2007 Starter Site to the CSharp Site.

• Using Commerce Server 2007 Inventory Adapter

In this lab, you will use the Microsoft Commerce Server 2007 Inventory adapter with Microsoft BizTalk Server 2006 to export an inventory catalog from the Commerce Server 2007 Starter Site to the same inventory catalog within the CSharp Site.

• Using Commerce Server 2007 Orders Adapter

In this lab, you will use the Microsoft Commerce Server 2007 Orders adapter with Microsoft BizTalk Server 2006 to export new orders from the Commerce Server 2007 Starter Site to a specified file directory.

• Using Commerce Server 2007 Profiles Adapter

In this lab, you will use the Microsoft Commerce Server 2007 Profiles adapter with Microsoft BizTalk Server 2006 to export new user profiles from the Commerce Server 2007 Starter Site to the CSharp Site.

Good luck!

I learned a new twist to the following error message today:

The adapter “SQL” raised an error message. Details “Unable to enlist in the transaction. (Exception from HRESULT: 0x8004D00A)”.

This can occur in a scenario where your BizTalk server attempts to connect to a separate SQL Server database and execute a distributed transaction.  In order for this to work the BizTalk server must have the ability to “hand-off” the transaction to SQL Server.  Typically, when you receive this error, it’s because the Distributed Transaction Coordinator (DTC) service is disabled or network DTC access is disabled.  These are the default settings in Windows Server 2003.  Take a look at the following article:

http://support.microsoft.com/?kbid=816701

There’s an additional twist to this scenario.  I found myself in a situation where I was receiving this error but had DTC setup correctly on all the machines in my BizTalk group and SQL Server cluster.  Nevertheless, the distributed transactions failed.  Then I found the following article:

http://msdn2.microsoft.com/en-us/library/aa561924.aspx

Turns out that, in order for DTC to work, the SQL Server must be able to resolve the NetBios name of the client (the BizTalk servers, in this case).  If it cannot resolve the NetBios name the transaction will fail.  In my environment, a firewall prevented the ability to resolve the NetBios name to an IP address thereby preventing the distributed transaction from processing.

To resolve this, I updated the HOST files on the SQL Server cluster so that they were able to resolve the NetBios names to an IP address.  Literally, moments after saving the HOST file, all my records started getting written into the database.

As I said, a different twist to a common problem.

I hope this helps!

As I mentioned in a previous blog, I’ve been setting up BizTalk 2006 in a 64-bit Windows Server 2003 environment.  This BizTalk solution communicates to AS/400 and Oracle, so I’ve been using the Microsoft BizTalk Adapters for Enterprise Applications (for Oracle connectivity) as well as Microsoft BizTalk Adapters for Host Systems (for AS/400 DB2 connectivity).

Setting up these adapters has not gone extremely well in the 64-bit O/S (whereas a 32-bit O/S is quite simple to configure).  I’ve been set back about a week because many different issues related to the 64-bit environment (and a few other issues).  In this post, I want to explain the issues I’ve encountered with regards to the Oracle adapter in a Windows Server 2003 64-bit environment.

This post assume that you’ve already installed your Oracle client.  Check out my post Using the “ODBC Adapter for Oracle Database” in BizTalk 2006 for information on how to install the client.  However, if you’re installing on a 64-bit machine, stop after you install the client.  The 64-bit world is quite different …

1. Install the .NET Framework 1.1 and SP 1.

The Oracle adapter requires the .NET Framework 1.1 and SP 1.  My 64-bit environment didn’t have the .NET Framework 1.1 installed, so this was an additional step I had to take.  This was the easiest of all the steps I had to take …

2. Create the ODBC connection.

Turns out that you cannot simply run Data Sources (ODBC) from Administrative Tools.  You have to run %WINDIR%\SysWOW64\odbcad32.exe, which invokes the 32-bit version of the Data Sources (ODBC) GUI.  See my post Adding ODBC connections in Windows Server 2003 64-bit for more information.

3. Install the Microsoft BizTalk Adapters for Enterprise Applications.

I only installed Oracle (r) Database.  Surprisingly, with the .NET Framework 1.1 and SP 1 installed, this goes very well.

4. Update registry settings for the Microsoft BizTalk Adapters for Enterprise Applications.

Turns out that some of the registry keys that are written during the installation are wrong (or rather, they’re not interpreted correctly).  Browse to the following registry key: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\BizTalkAdapters.  Two of the values, InstallDir and InstallPath, need to be changed.  Do the following:

1. Change InstallDir from “C:\Program Files (x86)\Microsoft BizTalk Adapters for Enterprise Applications” to “C:\Progra~2\Microsoft BizTalk Adapters for Enterprise Applications”.

2. Change InstallPath from “C:\Program Files (x86)\Common Files\Microsoft BizTalk Adapters for Enterprise Applications\” to “C:\Progra~2\Common Files\Microsoft BizTalk Adapters for Enterprise Applications\”.

Yes, for some reason, you have to change “Program Files (x86)” to “Progra~2″, probably because the Adapter isn’t written very well.  If you don’t update these registry settings, you will most likely get the following error:

The description for Event ID ( 0 ) in Source ( Microsoft BizTalk Adapters for Enterprise Applications ) cannot be found. The local computer may not have the necessary registry information or message DLL files to display messages from a remote computer. You may be able to use the /AUXSOURCE= flag to retrieve this description; see Help and Support for details. The following information is part of the event:     Exception occurred:
            Error Code: 12154 (0x2f7a)
        08004 : [Oracle][ODBC][Ora]ORA-12154: TNS:could not resolve service name.

5. Update additional registry settings to fix permission errors if you are using domain groups for authentication.

Your domain groups will not have access to the Oracle adapter by default.  In order to allow the runtimeagent.exe (which is the executable that is spawned and runs the Oracle adapter) to run appropriately, it needs to be able to access a registry key.  See the following article for more information: http://support.microsoft.com/?id=923650.

Do the following to resolve this issue (from the article):

1. Locate the following registry key: HKEY_LOCAL_MACHINE\Software\Wow6432Node\Microsoft\BizTalkAdapters\Config

[** Thanks to Steef-Jan Wiggers for noting that I forgot to display the 32-bit path in the Wow6432Node key]

2. Right-click the registry key that you located in step 1, and then click Permissions.

3. On the Security tab, click Add.

4. Type the domain group or the domain user account that is configured as the BizTalk host instance, and then click OK.

5. On the Security tab, click the domain group or the domain user account that you added in step 4, click to select the Read check box, and then click OK.

If you don’t update these registry settings, you will most likely get the following (unhelpful) error:

“RuntimeAgent: Error trapped in constructor: No connection could be made because the target machine actively refused it”

Error transmitting message: No connection could be made because the target machine actively refused it

6. Update the security permissions on your Oracle folder.

This is the most bizarre step of all, and it’s not particular to the 64-bit environment.  Oracle software requires that you give the Authenticated User privilege to the Oracle Home.  In most cases, your Oracle agent will not be the Administrator account (or at least, I hope it’s not).  However, there seems to be an issue with the permissions associated to Authenticated Users.  Consequently, the agent you specify to run the Oracle “runtimeagent.exe” is unable to gain access to the folder.  You might see the following error:

IM003 : Specified driver could not be loaded due to system error  5

To resolve this problem, you have to do the following:

1. Log on to Windows as a user with Administrator privileges.

 

2. Launch Windows Explorer from the Start Menu and and navigate to the ORACLE_HOME folder. This is typically the “Ora92″ folder under the “Oracle” folder (i.e. D:\Oracle\Ora92).

 

3. Right-click on the ORACLE_HOME folder and choose the “Properties” option from the drop down list. A “Properties” window should appear.

 

4. Click on the “Security” tab of the “Properties” window.

 

5. Click on “Authenticated Users” item in the “Name” list (on Windows XP the “Name” list is called “Group or user names”).

 

6. Uncheck the “Read and Execute” box in the “Permissions” list under the “Allow” column (on Windows XP the “Permissions” list is called “Permissions for Authenticated Users”).

 

7. Re-check the “Read and Execute” box under the “Allow” column (this is the box you just unchecked).

 

8. Click the “Advanced” button and in the “Permission Entries” list make sure you see the “Authenticated Users” listed there with:

 

Permission = Read & Execute

Apply To = This folder, subfolders and files

 

If this is NOT the case, edit that line and make sure the “Apply onto” drop-down box is set to “This folder, subfolders and files”. This should already be set properly but it is important that you verify this.

 

9. Click the “Ok” button until you close out all of the security properties windows. The cursor may present the hour glass for a few seconds as it applies the permissions you just changed to all subfolders and files.

 

10. Reboot your computer to assure that these changes have taken effect.

Yes, I was in as much shock as you are.  Uncheck a flag, and then re-check it.  I lost almost three days because of this bug.

That’s about it!  A series of (mostly) undocumented steps that are required in order to get the Oracle adapter to function in a 64-bit environment.  Fortunately, I had some great support from the escalation engineer’s with the Microsoft Product Support Services group.

I hope this post helps someone else avoid much of the pain and agony I had to go through …

Best of luck!