The finer points of the WSS adapter
I have recently finished a project for a client that used the IBS model. Infopath -> BizTalk -> Sharepoint. In this application the Infopath client used several web services. Some were hosted in IIS, and some in BizTalk. When the user submitted the form, it was sent to a BizTalk orchestration exposed as a web service for processing before being stored in a WSS doclib. [In IP you have to send only the data, not the entire form, to the web service.]
The orchestration was nicknamed the router. It did some server side validation (you should never rely on client side validation, that is just there for the user's UX benefit). It also dynamically configured the WSS send port, and did some other housecleaning tasks. Each form was for a different business unit (more than fifty options). The router determined which site (based on audit year) and doc lib (based on business unit) the form should be sent to.
While doing this project we learned a bit about the WSS adapter that we hadn't run into in prior projects.
Office Integration. The WSS adapter has an option for 'office integration'. When an infopath form is submitted it will use this setting to integrate with an infopath solution that has been published to a sharepoint form library. This is handy. At the top of each 'form' for IP (the data fragment) there are some processing instructions (PI's) that tell Windows that this is an infopath form, and where it should go get the form template (the visual display of the data basically); in this scenario, which sharepoint server and doclib holds the form template. It is nice that the adapter adds these to the data for you when it is sent to the wss site because these PI's can't be in the data when submitted via SOAP to a web service. It would hoark things all up. The downside is that it isn't terribly intelligent about how and what PI's it adds. The adapter will cover the basics, but it will not handle the file attachment PI's you need if files have been attached to the infopath form. In order to fix this, you have to disable office integration for the port, and set the PI's yourself in your orchestration, along with whatever other dynamic port properties you need.
// assign the message
FormOut = FormIn;
//adjust the file attachment PI
FormOut(XMLNORM.ProcessingInstructionOption) = 1;
FormOut(XMLNORM.ProcessingInstruction) = "";
// set the file name
strFileName = FormIn.ControlInfo.UnitName + "_" + FormIn.ControlInfo.ControlName;
strFileName = System.Text.RegularExpressions.Regex.Replace(strFileName, @"\.","_");
FormOut(WSS.Filename) = strFileName + ".xml";
//if a form document is found on the library, overwrite it.
FormOut(WSS.ConfigOverwrite) = "yes";
FormOut(WSS.ConfigOfficeIntegration) = "no";
Document Versioning. We also found out that the WSS adapter does not partake in the document versioning feature of WSS doc libraries. We had hoped to leverage this in our solution that a poorly submitted document could be rolled back. These documents are worked on by a global team over the course of a year, and things can happen. So, we don't know WHY versioning doesn't work for the adapter (maybe it bypasses the process somehow?), but it doesn't work. It's a shame really. Adrian confirmed this for us. He has a great blog, some great webcasts, and works on the adapter for MS. He is also very active in the TechNet newsgroups. Our workaround was for the routing orchestration to always submit a copy of the message to an archive doclib (one for each audit year). We let the adapter auto-rename the document if there was already one in there with that name. Our form submissions are named for us by the orchestration following a standard pattern. Only the business admin user has access to this archive doclib. They will be able to go in there and get any of the older versions they need. It's old fashion, and will likely bloat their content db for WSS, but it will work. The business user promised to go in and 'garden' the folder every once in a while to keep it fit and trim.
Go Speed Racer! Go! Another bug-a-boo we ran into was a race condition between the submitted form in infopath running through BTS and how long it took infopath to release it's lock on the file in WSS. The orchestration was beating infopath everytime. We had to put a timeout/retry on the WSS adapter. The first attempt would still fail, but it would succeed on the second try because we set the retry interval to 10 seconds. Why so short? Why not? The users would submit their form, and then alt-tab back to the WSS browser and hit refresh to see their updates. This changes the retry to 10 seconds, instead of the default five minutes.
Here was the error we were receiving:
Error Detais: Microsoft.Sharepoint.SPException
the file xxxx.xml is checked out or locked for editing by user
Form, name thyself! In an infopath form, there is a property on the file manu that determines the form's identity. This is a secret identity that is hidden (sort of) form the user. We wouldn't want to expose the user to anything hi-tech or anything. This form name, and namespace mashup is used by Infopath to determine if that form in is it's local cache or not. If it is, then the version numbers are compared, and if they match, then the local version is used. If not, it will ask you if you (the user) want to upgrade the form. Infopath will then download the new form and update the cache. This is all fine and dandy. Until we use it. We had the same form published to several different doclibs, one for each audit year. Since each audit year had it's own WSS site, we used a consistant structure to the site. The main doclib for these forms was always named the same, just the root URL of the path changed based on the audit year (2005, 2006, etc.). These forms werent' totally identical. There were some very minor differences, at least at this point. For example, the 'year' on the form was defaulted to the year of the audit site the form was published to. The form on the 2005 site had that field default to 2005, whereas is was 2006 on the 2006 audit site. Confused yet? Infopath also auto-verison numbers itself (if you want). So when we published to 2005, it was version 1.1. When we made the minor tweak, adn publish to 2006 it would change to 1.2 (trivial sample in this case, the version numbers are four dimensional). What would happen is, as a user bounced from year to year they were constantly being nagged to upgrade their form becuase it was out of date.
Well, you can't have that. So I thought I would give a custom form name (different from the file name) to each version. This would mutliply the number of distict files of the template, but would seperate them in the cache, and avoid this multiple personality issue. Every time I would then publish the form to the WSS doclib, it would overwrite the form name back to what it was.
In reality it was changing it to match the name of the doclib itself during the form publish. It was a coincidence that this is what the form name was originally. This took me some time to figure this out. This stumped us for a while. This doclib name really needed to stay teh same from year to year, we didn't want to have to rework all of the routing orchestrations, etc. We solved it by changing the name of the doclib to. The web address (URL) stayed the standardized , but when we published the infopath solution to the doclib, the form name would be set to something unique, at least in out solution. This was a hidden action inside IP/WSS that we didn't know about, and it was hard to figure it out. It was very confusing, and frustrating, as I am sure this post seems.
-bhp
The orchestration was nicknamed the router. It did some server side validation (you should never rely on client side validation, that is just there for the user's UX benefit). It also dynamically configured the WSS send port, and did some other housecleaning tasks. Each form was for a different business unit (more than fifty options). The router determined which site (based on audit year) and doc lib (based on business unit) the form should be sent to.
While doing this project we learned a bit about the WSS adapter that we hadn't run into in prior projects.
Office Integration. The WSS adapter has an option for 'office integration'. When an infopath form is submitted it will use this setting to integrate with an infopath solution that has been published to a sharepoint form library. This is handy. At the top of each 'form' for IP (the data fragment) there are some processing instructions (PI's) that tell Windows that this is an infopath form, and where it should go get the form template (the visual display of the data basically); in this scenario, which sharepoint server and doclib holds the form template. It is nice that the adapter adds these to the data for you when it is sent to the wss site because these PI's can't be in the data when submitted via SOAP to a web service. It would hoark things all up. The downside is that it isn't terribly intelligent about how and what PI's it adds. The adapter will cover the basics, but it will not handle the file attachment PI's you need if files have been attached to the infopath form. In order to fix this, you have to disable office integration for the port, and set the PI's yourself in your orchestration, along with whatever other dynamic port properties you need.
// assign the message
FormOut = FormIn;
//adjust the file attachment PI
FormOut(XMLNORM.ProcessingInstructionOption) = 1;
FormOut(XMLNORM.ProcessingInstruction) = "";
// set the file name
strFileName = FormIn.ControlInfo.UnitName + "_" + FormIn.ControlInfo.ControlName;
strFileName = System.Text.RegularExpressions.Regex.Replace(strFileName, @"\.","_");
FormOut(WSS.Filename) = strFileName + ".xml";
//if a form document is found on the library, overwrite it.
FormOut(WSS.ConfigOverwrite) = "yes";
FormOut(WSS.ConfigOfficeIntegration) = "no";
Document Versioning. We also found out that the WSS adapter does not partake in the document versioning feature of WSS doc libraries. We had hoped to leverage this in our solution that a poorly submitted document could be rolled back. These documents are worked on by a global team over the course of a year, and things can happen. So, we don't know WHY versioning doesn't work for the adapter (maybe it bypasses the process somehow?), but it doesn't work. It's a shame really. Adrian confirmed this for us. He has a great blog, some great webcasts, and works on the adapter for MS. He is also very active in the TechNet newsgroups. Our workaround was for the routing orchestration to always submit a copy of the message to an archive doclib (one for each audit year). We let the adapter auto-rename the document if there was already one in there with that name. Our form submissions are named for us by the orchestration following a standard pattern. Only the business admin user has access to this archive doclib. They will be able to go in there and get any of the older versions they need. It's old fashion, and will likely bloat their content db for WSS, but it will work. The business user promised to go in and 'garden' the folder every once in a while to keep it fit and trim.
Go Speed Racer! Go! Another bug-a-boo we ran into was a race condition between the submitted form in infopath running through BTS and how long it took infopath to release it's lock on the file in WSS. The orchestration was beating infopath everytime. We had to put a timeout/retry on the WSS adapter. The first attempt would still fail, but it would succeed on the second try because we set the retry interval to 10 seconds. Why so short? Why not? The users would submit their form, and then alt-tab back to the WSS browser and hit refresh to see their updates. This changes the retry to 10 seconds, instead of the default five minutes.
Here was the error we were receiving:
Error Detais: Microsoft.Sharepoint.SPException
the file xxxx.xml is checked out or locked for editing by user
Form, name thyself! In an infopath form, there is a property on the file manu that determines the form's identity. This is a secret identity that is hidden (sort of) form the user. We wouldn't want to expose the user to anything hi-tech or anything. This form name, and namespace mashup is used by Infopath to determine if that form in is it's local cache or not. If it is, then the version numbers are compared, and if they match, then the local version is used. If not, it will ask you if you (the user) want to upgrade the form. Infopath will then download the new form and update the cache. This is all fine and dandy. Until we use it. We had the same form published to several different doclibs, one for each audit year. Since each audit year had it's own WSS site, we used a consistant structure to the site. The main doclib for these forms was always named the same, just the root URL of the path changed based on the audit year (2005, 2006, etc.). These forms werent' totally identical. There were some very minor differences, at least at this point. For example, the 'year' on the form was defaulted to the year of the audit site the form was published to. The form on the 2005 site had that field default to 2005, whereas is was 2006 on the 2006 audit site. Confused yet? Infopath also auto-verison numbers itself (if you want). So when we published to 2005, it was version 1.1. When we made the minor tweak, adn publish to 2006 it would change to 1.2 (trivial sample in this case, the version numbers are four dimensional). What would happen is, as a user bounced from year to year they were constantly being nagged to upgrade their form becuase it was out of date.
Well, you can't have that. So I thought I would give a custom form name (different from the file name) to each version. This would mutliply the number of distict files of the template, but would seperate them in the cache, and avoid this multiple personality issue. Every time I would then publish the form to the WSS doclib, it would overwrite the form name back to what it was.
In reality it was changing it to match the name of the doclib itself during the form publish. It was a coincidence that this is what the form name was originally. This took me some time to figure this out. This stumped us for a while. This doclib name really needed to stay teh same from year to year, we didn't want to have to rework all of the routing orchestrations, etc. We solved it by changing the name of the doclib to
-bhp
Comments
A> W