BizTalk Adapter Pack 2.0 – SAP Adapter IDoc Schema Versioning Part 2

In my first post, I discussed how the BizTalk Adapter pack Consume Adapter Service wizard tightly couples the IDoc schema version with the version of SAP that you used to generate the schema with.  The goal of this post is to discover how you can avoid this tight coupling and hopefully survive an SAP upgrade.  I know the organization that I work for would not be pleased with having to update all of our IDoc schemas when we do our next SAP Upgrade just because the version of SAP has been incremented.

When the BizTalk Adapter Pack came out I was pretty excited that I could throw away my Flat File schemas and pipelines.  While true, it comes at a cost.  When using the XML Receive pipeline with the new Adapter, the Adapter will use data in the SAP Control record to determine what version of the message you retrieving from SAP and will assign a namespace to your message, that contains SAP version information, before depositing it in the message box. If have not changed your SAP version since generating your IDocs you are in business.  If you have upgraded your SAP system or have generated the wrong schemas for your SAP version then you will be in a lot of pain. 

To get around this tight coupling issue, you can revert back to the old style of IDoc processing which involves flat files and pipelines.  Now there is nothing really wrong with this model, but it does require a few extra steps and is not as “clean” a solution as using the XML Receive pipeline.

I will now take you through how you generate a flat file schema that can be used to process different versions of the same IDoc.  When I say different schemas this means that the version, and therefore namespace, are different but structurally the documents are the same.  Note that I will not go through all steps required to generate an IDoc schema, only those that are important to generate a Flat File schema.  To see a more comprehensive walk through of generating an IDoc schema, please see my Webcast.

 

• When using Consume Adapter Service wizard, ensure that “GenerateFlatFileCompatible” is set to true.

When you set the GenerateFlatFileCompatible property to true, you will now see the flat file specific data within the Schema specification.

Without setting GenerateFlatFileCompatible ,  the schema will not contain this flat file information.

• You also want to indicate the “ReceiveIDocFormat” will be a String.  You will find out why this is important later on in this post.

• Once the schemas have been imported into Visual Studio, enable “Flat File Extensions” to the “core schema”.  When using the BizTalk Adapter Pack Consume Adapter Service wizard you will generate more than 1 schema unlike the old .Net Connector version where you would always only generate 1 schema.  By “core schema” I mean the one that contains the “meat” of your schema, not one that contains the shell(all of the imported schemas) or any of the base type schemas.

• You will now need to create a Receive Pipeline and add a Flat File disassembler

• Add your “shell” schema to the document schema property

• Build and Deploy your application
• When configuring your SAP Receive location you will want to specify your Receive Pipeline as opposed to XML Receive

• On the Binding tab, set the “ReceiveIdocFormat” to String

• On the Messages tab, provide an XPath expression that will extract the flat file data so it can be disassembled by the Receive Pipeline.  The XPath expression that I used is:

  /*[local-name()='ReceiveIdoc']/*[local-name()='idocData']

  The adapter is essentially wrapping this flat file in XML tags so that it can make it through the adapter stack as an XML message. 

  Also ensure the “Node encoding” is set to String as the default is “XML”

• Start your application and you are good to go

 

• Up until this point, I have not modified the namespace of my schema and everything worked well as expected

 

 

• However, the purpose of this post is to demonstrate how we can break away from the default namespaces that are generated by the adapter.

• Since I have redeployed the application, the message subscription have also been updated:

 

• Start your application up and it should function with this new namespace and therefore subscription.

 

• The next test is to generate a different version of an SAP IDoc and ensure receiving a different version of the IDoc does not break our application.  If you recall from Post 1 we received an error in this situation.  From the Consume Adapter Service wizard, I am deliberately going to generate a schema that has a DOCREL  greater than my current SAP version.

• My subscription is updated and is looking for a “710” IDoc where as SAP is going to generate a
  “700” IDoc

• I received, processed and delivered the message downstream without issue

• Even though SAP, populated the Control record with DOCREL = 700, I am able to process this message because this DOCREL is not being used to derive the target namespace like it is when you use the XML Receive pipeline.  This is really where the value of the Flat file pipeline comes in as it will use the namespace in the schema that is configured inside the pipeline instead of having the Adapter generate a namespace automatically.   This also works as the structure of the 700 IDoc has not changed in the 710 IDoc.  If the structure of the IDoc changes with the version number then you have no other option than to regenerate your schemas.

 Gotcha!

So everything is fine and dandy until you try to deploy another IDoc with the same Program Id/Partner Profile.  There is bug with the BizTalk Adapter Pack that prevents you from deploying multiple IDoc Flat File schemas with the same Program ID.  Look for a workaround with my next post in this series.  I should be able to turn that post around quicker than this one.