Connecting to the Elemica Network with BizTalk Accelerator for RosettaNet 3.0

Microsoft Corporation

April 2005

Applies to: Microsoft BizTalk Accelerator for RosettaNet 3.0

Summary: This document describes how to enable Microsoft BizTalk Accelerator for RosettaNet (BTARN) 3.0 to connect to the Elemica Exchange Server Provider (ESP). (4 printed pages)

This document accompanies the Elemica Connectivity Pack. Download here

Connect to Elemica

To customize BTARN to connect to Elemica, you must follow these steps:

  • Install BTARN Hotfixes
  • Edit the process configuration
  • Edit agreements
  • Download project files
  • Update Microsoft.Solutions.BTARN.RNIFReceive.dll
  • Update Microsoft.Solutions.BTARN.RNIFSend.dll and set the BTARN configuration for client certificates

The changes to Microsoft.Solutions.BTARN.RNIFReceive.dll and Microsoft.Solutions.BTARN.RNIFSend.dll have been made in the RNIFReceive.csproj and RNIFSend.csproj project files that are part of the WebApplication.zip. You can download these projects from https://go.microsoft.com/fwlink/?LinkId=46195. Use these projects as is instead of creating them from scratch.

This document describes the above steps in detail.

Install BTARN Hotfixes

To connect to Elemica, you must install the BTARN Hotfixes listed in Table 1.

Note: These Hotfixes provide support for the RNIF 1.1 schemas, mainly the enumerations, required by Elemica Marketplace.

Table 1 Installing BTARN Hotfixes

Hotfix Number Fix URL

Q889523

FIX: The BizTalk Accelerator for RosettaNet 3.0 does not successfully process RosettaNet Implementation Framework (RNIF) 1.1 acknowledgement messages

https://support.microsoft.com/default.aspx?scid=kb;en-us;889523

Q891072

The BizTalk Accelerator for RosettaNet 3.0 object identifier for MD5 is not correct for the RNIF 1.1 implementation

https://support.microsoft.com/default.aspx?scid=kb;en-us;891072

Q890928

FIX: The BizTalk Accelerator for RosettaNet 3.0 incorrectly uses the local time instead of UTC time in the DateTimeStamp fields of RosettaNet messages

https://support.microsoft.com/default.aspx?scid=kb;en-us;890928

Q890071

FIX: You may receive a validation error message when the BizTalk Server Accelerator for RosettaNet 3.0 processes a signal that contains a value for the GlobalPartnerClassificationCode element that is outside the predefined enumerations

https://support.microsoft.com/default.aspx?scid=kb;en-us;890071

Q896496

Fix for the Preamble namespace for RNIF 1.1

https://support.microsoft.com/default.aspx?scid=kb;en-us;896496

Edit the Process Configuration

In the Process Configuration used for connecting with Elemica, set the standard to CIDX, as shown in Figure 1.

Note: For more information about setting the standard in a Process Configuration, see "How to Create or Edit a Process Configuration" in Microsoft BizTalk Accelerator for RosettaNet 3.0 Help.

Figure 1 Setting the Standard to CIDX

Edit Agreements

For every agreement, add a custom property "AAR" (IsAcceptanceAckRequired), and set its value to False, as shown in Figure 2.

Note: You must add an IsAcceptanceAckRequired custom property because Elemica requires only Receipt Acknowledgement, not Acceptance Acknowledgement.

Note: For more information about adding a custom property to an agreement, see "Creating or Editing an Agreement" in Microsoft BizTalk Accelerator for RosettaNet 3.0 Help.

Figure 2 Adding a Custom Property IsAcceptanceAckRequired

Download the Project Files

To connect to Elemica, you must edit the Microsoft.Solutions.BTARN.RNIFReceive.dll and Microsoft.Solutions.BTARN.RNIFSend.dll files as described in the following topics. These changes have been made in the RNIFReceive.csproj and RNIFSend.csproj project files that are part of the WebApplication.zip file. You can download these project files from https://go.microsoft.com/fwlink/?LinkId=46195. Use these projects as is instead of creating them from scratch.

The RNIFReceive project files include the following:

  • AssemblyInfo.cs
  • RNIFReceive.aspx
  • RNIFReceive.aspx.cs
  • RNIFReceive.aspx.resx
  • RNIFReceive.csproj
  • RNIFReceive.csproj.webinfo
  • StringResources.resx
  • Web.config

The RNIFSend project files include the following:

  • AssemblyInfo.cs
  • RNIFSend.aspx
  • RNIFSend.aspx.resx
  • RNIFSend.csproj
  • RNIFSend.csproj.webinfo
  • StringResources.resx
  • Web.config

Update Microsoft.Solutions.BTARN.RNIFReceive.dll

To connect to Elemica, you must change the return HTTP status setting in Microsoft.Solutions.BTARN.RNIFReceive.dll file. These changes have been made in the RNIFReceive project files that you can download as part of the Elemica Connectivity Pack from https://go.microsoft.com/fwlink/?LinkId=46195.

The original RNIFReceive project is in the BTARN SDK folder under the WebApplication folder. The changes from the original RNIFReceive project are the following:

  • Added a new application setting in the Web.config file (Elemica) that can be set to True or False.
  • Added logic to the RNIFReceive.aspx.cs file to return status 200 if the application setting is set to True.

To compile and use the new RNIFReceive project, continue as follows:

  1. Copy the RNIFReceive project to a local folder on the computer.

  2. Click Start, point to All Programs, point to Microsoft Visual Studio .NET 2003, point to Visual Studio .NET Tools, and then click Visual Studio .NET 2003 Command Prompt.

  3. At the command prompt, move to the folder where that you pasted the project to.

  4. At the command prompt, type "sn -k Signing.snk" to create a key pair needed to compile the project, and then press Enter.

  5. Start Internet Information Services (IIS) Manager.

  6. Create a new application pool and set its identity to Network Services.

  7. Create a new virtual directory running under the newly created application pool. The virtual directory should point to the folder where you pasted the RNIFReceive project.

  8. Change the settings on the new virtual directory to Enable anonymous access and make sure that Integrated Windows Authentication is not selected.

  9. Open the RNIFReceive.csproj project in Visual Studio .NET. Add a reference to the assembly Microsoft.Solutions.BTARN.Shared.dll found under <drive>:\Program Files\Microsoft BizTalk Accelerator for RosettaNet 3.0\Bin, and set the assembly key file for the project to Signing.snk.

  10. Build and compile the project in Visual Studio .NET. Visual Studio will generate a new Microsoft.Solutions.BTARN.RNIFReceive.dll file under the folder Bin.

  11. To enable connectivity to Elemica, edit the Web.config file to uncomment the following line:

    <!-- <add key="Elemica" value="true" /> -->
    
  12. Restart IIS.

Enable Client Certificate Authentication in BTARN

To connect to the Elemica network, you must create public and private client certificates and import them into BTARN 3.0. For more information about certificates in BTARN 3.0, see "Managing Certificates" and "Step 2: Creating Public and Private Certificates", in the "Preparing for the Double-Action Tutorial" node,in Microsoft BizTalk Accelerator for RosettaNet 3.0 Help.

Update the Microsoft.Solutions.BTARN.RNIFSend.dll and Set the BTARN Configuration for Client Certificates

To connect to Elemica, you must update the Microsoft.Solutions.BTARN.RNIFSend.dll file to support client certificates and set the configuration for client certificates as described in this topic. These changes have been made in the RNIFSend project files that you can download as part of the Elemica Connectivity Pack from https://go.microsoft.com/fwlink/?LinkId=46195.

The original RNIFSend project is in the BTARN SDK folder under the WebApplication folder. The changes from the original RNIFSend project are the following:

  • A new application setting in the Web.config file (CertificateFile) that you can set to point to a DER encoded binary X.509 certificate
  • A change to the Web.config file to allow for Windows Authentication, which enables the RNIFSend.aspx page to load a client certificate from a personal certificate store
  • A reference to the assembly System.Security.Cryptography.X509Certificates has been added
  • A new method LoadCertificate that loads the certificate specified in the Web.config file has been invoked within the method CreateOuterHttpRequest

To compile and use the new RNIFSend project, continue as follows:

  1. Copy the RNIFSend project to a local folder on the computer.

  2. Click Start, point to All Programs, point to Microsoft Visual Studio .NET 2003, point to Visual Studio .NET Tools, and then click Visual Studio .NET 2003 Command Prompt.

  3. At the command prompt, move to the folder that you pasted the project to.

  4. At the command prompt, type "sn -k Signing.snk" to create a key pair needed to compile the project, and then press Enter.

    Note: You can also use the same key pair generated in "Update Microsoft.Solutions.BTARN.RNIFReceive.dll".

  5. Start Internet Information Services (IIS) Manager.

  6. Create a new application pool and set its identity to a new local user, for example, HttpHostSvc.

  7. Add the user HttpHostSvc to the local groups IIS_WPG and STS_WPG.

  8. Create a new virtual directory running under the newly created application pool. The virtual directory should point to the folder where you pasted the RNIFSend project.

  9. Change the settings on the new virtual directory to Enable anonymous access, and make sure that Integrated Windows Authentication is not selected.

  10. Open the RNIFSend.csproj project in Visual Studio .NET. Add a reference to the assembly Microsoft.Solutions.BTARN.Shared.dll found under <drive>:\Program Files\Microsoft BizTalk Accelerator for RosettaNet 3.0\Bin, and set the assembly key file for the project to Signing.snk.

  11. Build and compile the project in Visual Studio .NET. Visual Studio will generate a new Microsoft.Solutions.BTARN.RNIFSend.dll file under the folder Bin.

  12. To enable connectivity using a client certificate, edit the Web.config file to uncomment the following line:

    <!-- <add key="CertificateFile" value="C:\Documents and Settings\HttpHostSvc\Application Data\Microsoft\BizTalk Accelerator for RosettaNet 3.0\ClientCertificate.der" /> -->
    
  13. Log out from the computer and log back in as the user HttpHostUser. Run the Certificates MMC. Import the client certificate to the "Personal" certificate store.

    Important: Make sure that you have imported the private key. You can verify this by looking at the properties of the certificate in the personal store. You should see a small icon of a key in the lower left part of the Properties dialog box.

  14. Export the certificate to a "DER encoded binary X.509 (.CER)" file. Make sure not to export the private key. Save the .der file as <drive>:\Documents and Settings\HttpHostUser\Application Data\Microsoft\BizTalk Accelerator for RosettaNet 3.0\ClientCertificate.der.

    Note: The path in the code above presumes the user is HttpHostUser.

    Note: When the ASPX page loads, it will assume the security context of HttpHostUser.

  15. On your BizTalk server, edit the value of the following registry key to point to the URL of the new ASPX page in the new virtual directory:
    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\BizTalk Accelerator for RosettaNet 3.0\Configuration\RNIFSenderURI

    Note: Now when you send a transaction, RNIFSend.aspx will use the client certificate to connect to the destination URL. Make sure that you use the client certificate only with partners who require it. You may still have to edit the .aspx.cs file to accomplish this.

    Note: The new URL, in the registry, will only be applied to new partners that are created. If you have partners that have already been created, you may have to edit the URLs in their corresponding HTTP send ports in BizTalk Explorer. These send ports have the following format: <PARTNER NAME>.Async and <PARTNER NAME>.Sync.

    Note: In case you have to connect to only a few specific partners using a client certificate, you do not have to edit the registry key. Instead, you have to edit the corresponding ports in BizTalk Explorer to point to the URL hosting the updated Microsoft.Solutions.BTARN.RNIFSend.dll file. The connection to the other partners will use the default .dll file in the default BTARNApp virtual directory.

  16. Restart IIS.