Creating a PIDX Partner Interface Process (PIP) in BTARN 3.5

The next step in developing your PIDX / RNIF solution using the BizTalk Accelerator for RosettaNet (BTARN 3.5) is to create a new Process Configuration from your PIDX PIP. I’m going to use the PIDX “Invoice” and “Invoice Response” PIPs (P21 & P22) in this example since they are generally the most important in the Energy, Oil & Gas industry right now.

1. You begin by opening the BTARN Management Console and right-clicking on the Process Configuration Settings node in the left-hand pane and selecting New > Process Configuration.

2. For PIDX configurations I recommend using a Display Code that includes the standard, the PIP and the version like “PIDX_P21_1.0”. This will make things a lot easier if you need to support multiple versions in the future. The Process Code corresponds to the PIP number which is “P21” in our case. The Version is “1.0” and the Process Name is “Invoice”. The Message Standard is “PIDX”, the Standard Version is “1.0” and the Payload Binding ID is also “PIDX. Once you are done, your General tab should look like this.

3. The parameters you set on the Activity tab are very important and the required values can be found in the PIDX Implementation Guide. To meet the PIDX requirements, the Non-Repudiation Required, Is Authorization Required and Non-Repudiation of Origin and Content parameters must all be set to “True” and the Type parameter must be set to “Request/Response”. The settings for all other parameters on the Activity tab must be agreed upon by both parties involved in the transaction. Once you are done, the Activity tab should look like this.

4. The parameters you set on the Initiator tab are also very important and these are all specified by the PIDX P21 Invoice PIP documentation. It’s very important that you communicate these settings to your trading partner as well since they must be the same on both messaging systems. Once you are complete the Initiator tab should look exactly like this.


5. The same goes for the Responder tab as shown here.

There are a lot of parameters to set when creating a new Process Configuration in the BizTalk Accelerator for RosettaNet. Almost all of these are used by the Initiator Private Process and Initiator Public Process to create the outbound RNIF headers and message so it’s vital that you and your trading partner agree on all these before you begin testing.

It’s pretty sad how complicated this is compared to an alternative such as AS2. As I’ve said before using RosettaNet is like “swatting a fly with an atom bomb”.

Currently listening to Eric Marienthal’s Just Around the Corner.

Posted in BizTalk Server, PIDX, RosettaNet | 3 Comments

Creating Home Organizations & Partners in BTARN 3.5

This is a fairly straight-forward task but since it’s the first thing you’ll need to configure in the BizTalk Accelerator for RosettaNet 3.5 (BTARN 3.5), I thought I’d walk through it anyway.

Creating a Home Organization

1. You begin by opening the BTARN Management Console and right-clicking on the Home Organization node in the left-hand pane.

2. Next you’ll need to add the home organization’s name, DUNS number (circled in red below), a brief description and then choose a Home organization classification from the drop-down menu.

3. Next you’ll need to add some contact information as shown here below.

4. Click Apply and OK to save your new Home Organization. It’s that simple.

Creating a Partner

1. This is virtually the same as creating a Home Organization and you’ll first create the Partner and then the partners’s name, DUNS number (circled in red below), a brief description and then choose a Partner classification from the drop-down menu. This also where you’ll set the Partner’s signature and encryption keys (certificates).

2. Next you’ll need to add some contact information as shown here below.

3. Click Apply and OK to save your new Partner. Again, it’s that simple.

If you take a look at the BizTalk Server 2006 Administration Console under the Parties node, you’ll see your new Home Organization and Partner in the list just as you would expect.

As I said, all very straight-forward! Don’t let this fool you however, later I’ll post about how to create a new Agreement and you’ll probably end up just as confused as I was the first time!

Currently listening to: Martina McBride’s For These Times

Posted in BizTalk Server, RosettaNet | Leave a comment

Understanding RosettaNet Message Flow in BizTalk Server 2006

If a picture is worth a thousand words, then these two diagrams (courtesy & copyright Microsoft) are worth millions! At least they are to anyone desperate to understand how the BizTalk Accelerator for RosettaNet (BTARN 3.5) really works.

Initiator Message Flow

Don’t let the complexity of this diagram scare you. The message flow for an outbound RNIF (or PIDX) message consists of four key areas.

  1. The SQL Server BTARN Databases where all “lob” messages (such as a P21 – PIDX Invoice) and any attachments are stored BEFORE the outbound RNIF message flow actually begins, and the SQL Receive Location used to process the message content and attachments into the MessageBox.

    Note: If you’re not sending attachments you may elect not to use SQL for this and can substitute FILE receive locations. The SDK contains sample code and a pretty good explanation of how this may work.

  2. The Initiator Private Process orchestration where the actual messages and attachments are “prepared” (usually transformed into XML) for further processing by the initiator public process.
  3. The Initiator Public Process orchestration where the outbound message is actually formatted to meet the RNIF standard. This includes adding the required RNIF headers and other such tasks. Consider this a “Black Box” since you can’t change how this works without invalidating the RosettaNet certification.
  4. The HTTP/HTTPS Send Ports and the RNIFSend.aspx web application that are CRITICAL to the correct processing of the outbound messages. This is where the real work is done to validate the messages, create the correct MIME headers and add the required RNIF DOCTYPE declarations.

    Just a side note. If you’re really interested in how this all works, you can look at the source code for this web application using Lutz Roeder’s Reflector. I think you’ll be amazed at how much Regex is used to “craft” these RNIF messages.

Responder Message Flow

The message flow for an inbound RNIF message (whether it’s a new message or an asynchronous response to a message you’ve already sent) consists of three key areas.

  1. The RNIFReceive.aspx web application which processes the inbound message, validates it and then removes all the RNIF specific headers and DOCTYPE declarations. This then passes the message along to the HTTP/HTTPS Receive Port and Pipeline which handles the non-repudiation, decodes the message, parses the message and resolves which Party it came from.
  2. The Responder Public Process receive the RNIF message from the MessageBox and extracts the content and attachments and sends them to the responder private process for further processing. Just like the initiator public process, the Responder Public Process should be considered a “Black Box” and left unchanged.
  3. The Responder Private Process then routes the inbound messages and any attachments to the SQL Server BTARN Databases where it can be further processed and sent to some “lob” back-end system.

There are a few other details involved in the message flow (signals) depending upon whether your transmission is synchronous or asynchronous, but the basics are fairly straight-forward. The best thing is that this workflow is almost entirely “configured” using the BTARN Management Console and is “message agnostic”, meaning that you can use any standard RNIF, CIDX or PIDX “PIP” (Partner Interface Process) that you and your trading partner both support.

Best of all, it’s included in the price of BizTalk Server 2006 R2!

Currently listening to Carrie Underwood’s Carnival Ride

Posted in BizTalk Server, Microsoft, PIDX, RosettaNet | 3 Comments

PIDX Schemas Solution for BizTalk Server 2006

One of the things you’ll need when working with PIDX / RNIF / BTARN projects in BizTalk Server 2006 is the actual PIDX schemas (.xsd) to be used. Luckily the American Petroleum Institute (API) has a public web site for the Petroleum Industry Data Exchange (PIDX) committee which contains links to the various versions of their schemas.

Once you and your trading partner decide on which version you’ll be using, you can download the schemas and add them to your BizTalk solution in Visual Studio. When you attempt to open these schemas you’ll notice an error message that pops up as shown here.

This is a fairly common error and usually occurs when the schema you are attempting to open contains a reference to another “imported” or “included” schema and the BizTalk Schema Editor tool cannot find the file in question. The work-around for this is fairly simple and all you’ll need to do is change these two attributes.

  1. First you’ll need to click on the Imports attribute collection and delete the reference to the PIDX Library schema which contains the hard-coded location which is incorrect.

  2. Next you’ll need to import a new schema as an XSD Include and select the PIDXLib from the picker as shown here.

  3. Once that step is complete, you’ll also need to change the Root Reference attribute so that the BizTalk Schema Editor knows how to correctly identify your schema.

And that’s really all there is to it, except you’ll have to do this for every PIDX schema and every version.

Good thing I’ve already done this and you can download the BizTalk Solution containing all the PIDX schemas right here!

Posted in BizTalk Server, Microsoft, PIDX, Rosetta Net, RosettaNet | 1 Comment

BizTalk Server 2006 – BTARN 3.5 Configuration Tips

Just a quick post to those of you planning to use the BizTalk Accelerator for RosettaNet 3.5. There are a few little “issues” that you need to know about before you get started.

Accounts, Hosts & Host Instances

BTARN 3.5 requires the use of Hosts that have the Authentication Trusted option enabled. This has to be configured BEFORE you create any Host Instances. I recommend creating a new Service Account, a new In-Process Host, a new Isolated Host and then a new Host Instance for each of these as shown in the table below. You will also need to create new HTTP and SQL Send Handlers and Receive Handlers as well.

Note: The In-Process Host Instance account and Isolated Host Instance account must be the same for BTARN to work properly!

Service Account: Domain\AccountName
In-Process Host: RosettaNetApplication
In-Process Host Instance: RosettaNetApplication
Isolated Host: RosettaNetIsolatedHost
Isolated Host Instance: RosettaNetIsolatedHost
SQL Send Handler: RosettaNetApplication
SQL Receive Handler: RosettaNetApplication
HTTP Receive Handler: RosettaNetIsolatedHost
HTTP Send Handler: RosettaNetApplication

Installation & Configuration

Don’t use “localhost” for your BizTalk Server or Web Server name when running the Configuration Wizard. Use the NetBIOS name of your BizTalk Server machine and the NetBIOS name of your Web Server machine instead. The Configuration Wizard will fail with a strange error if you use default “localhost”.

Why? I have no earthly idea but I will be submitting this to the BizTalk team as a bug!

One final note

All the BTARN bits are deployed to the BizTalk Application 1 by default. I’m still trying to find a way to isolate the RosettaNet bits (schemas, maps, pipelines, ports and orchestrations) in their own BizTalk Apllication much like the new EDI/AS2 bits are. I’ll post if I find an easy way to accomplish this.

Happy Integrations!


I just want everyone to know that I’m not really all that smart. I had a ton of help setting up BTARN 3.5 and getting things working properly! I hired the folks from Microsoft Consulting Services to come in and teach me everything I could learn about using RosettaNet in BizTalk Server 2006. Special thanks to Ross Santee! A great consultant.

Currently listening to: Dave Koz – Castle of Dreams

Posted in BizTalk Server, PIDX, RosettaNet | 7 Comments