%Filename% macro is not replaced with the disk filename

I’ve seen this issue showing a couple of times on the BizTalk Newsgroups so I thought it’s worth posting about this on my blog. The user expectation, which is probably correct from usability point of view, is that the %Filename% macro is replaced with the name of the original file no matter if that file was received from the disk through FILE adapter or from a document library through SharePoint adapter. This doesn’t happen like that since the WSS adapter send ports will resolve the %Filename% macro to empty string if the message was originally received from any other adapter than WSS adapter. This is by design.

The %Filename% macro is replaced with the name of the SharePoint file (and not with the name of a file on disk). If the message was received through FILE adapter (or any other adapter than WSS) then the %Filename% macro is probably replaced with empty string. Macros (like %Filename%) and context properties (like WSS.Filename) are implemented by each adapter separately, they are specific to each adapter, and there is no ‘framework’ that would provide a unified set of macros/context properties accross all adapters. This makes sense since ‘%Filename%’ might not make sense for a POP3 adapter or it could have a slightly different behavior for 3rd party adapters. Coincidently, some adapters have used the same macro name (I would guess %Filename% is a common one) and ocasionally the same context property. However, the %Filename% macro in a WSS adapter send port is totally different from a %Filename% macro in an FTP adapter send port, for instance.

To workaround this you can use an orchestration or a custom pipeline. All you need to do is get the disk file name from FILE.ReceivedFileName property and save it in the WSS.Filename property like below. Make sure that the Filename field in the send port UI dialog box is left empty so that the value supplied through the context property WSS.Filename is used to set the filename.
   sharepointOutgoingMsg(WSS.Filename) = diskIncomingMsg(FILE.ReceivedFileName);


You don’t have to use dynamic send ports for the workaround above. In the case of WSS adapter, you can define the send port configuration through the WSS.Config*, WSS.Filename context properties of the outgoing message and then configure the WSS send port equivalent properties so that they are either empty (text boxes) or have a value of Orchestration (drop-down boxes) in order to not overwrite the configuration information specified through the context properties.

Comments (10)

  1. Piers says:

    It seems relatively easy to do this within an orchestration, but I am not so sure how to do this with a custom pipeline. Do you have a custom pipeline example that does this? Thanks.

  2. Garry Trinder says:

    I don’t have a sample but I’m pretty sure you will find at least a few custom pipeline samples outthere if you search on the Internet.

  3. Piers says:

    I admit that I am fairly new to BizTalk, but I did do a search for custom pipelines and found plenty of good examples. But, all the examples deal with one incoming message, IBaseMessage in the Execute method. For what we are trying to do, we need to get the incoming message (diskIncomingMsg), retrieve the filename of that message and replace the outgoing message (sharepointOutgoingMsg) filename.

    The way I see to do this with a custom component in a pipeline would be to do the following:

    – Use the IPersistPropertyBag.Save method in the receive pipeline to save the diskIncomingMsg filename.

    – Use the IPersistPropertyBag.Load to retrieve the diskIncomingMsg filename in the send pipeline

    Or, possibly I could promote a property in the custom component in the receive pipeline and save the diskIncomingMsg filename there to be retrieved in the send pipeline?

  4. Garry Trinder says:

    You have only one message diskIncomingMsg that is modified in the pipeline, you don’t have nor do you need two messages. The WSS adapter uses the filename from the WSS.Filename context property. The only thing that you need to do in your receive pipeline, is to modify the diskIncomingMsg and copy the ‘filename’ value from the FILE.ReceivedFileName to the WSS.Filename context property. When the message exits the pipeline, the filename value will be present in both context properties. You will use IPersistPropertyBag.Load to load the filename value from the FILE.ReceivedFileName context property and then you will use IPersistPropertyBag.Save to save that value in the WSS.Filename property.

  5. svek says:

    How do you use WSS.Filename from a pipeline component?

    Don’t you have to you use the

    Context.Write(_PropertyName, _PropertyNamespace,. sPropertyValue) method?

    I haven’t been able to find what namespace the WSS-adapter uses. Has anyone else?

  6. Garry Trinder says:

    You can use BizTalk MMC to discover the namespace and all other details for adapters property schemas and more.

    Under BizTalk Group -> Applications -> BizTalk System -> Schemas, you will find the WSS.bts_WindowsSharePointServices_properties XSD schema that defines the WSS adapter namespace and properties.

    The property schema namespace for WSS adapter is ‘http://schemas.microsoft.com/BizTalk/2006/WindowsSharePointServices-properties

  7. Onur BIYIK says:

    I have created a simple orchestration to pass filename to wss adapter.

    I works ok for most file names. I know, not all NTFS file names are valid for sharepoint. But there are some files which i can upload manually but wss adapter appearently not.

    "ShowTv.RingtoneDistributor.DebitProxy[13-15].rar" is not a valid value for the ‘Filename’ property. Windows SharePoint Services file names can not contain more than one ‘.’ character.

    Is this a bug in wss adapter? How can i convert file names to be sharepoint compatible?

  8. Garry Trinder says:

    It’s a known limitation that’s documented here http://msdn2.microsoft.com/en-us/library/aa558724.aspx

    The design time file name will be expanded at runtime into Windows SharePoint Services file names. This Windows SharePoint Services file name has some additional limitations, which are described as follows:

    Valid Windows file names can contain any Unicode characters with the exception of the following: / : * ? < > | " # { } % & ~ or tab characters and multiple periods.

    The file name cannot be longer than 256 characters and the entire URL must be less than or equal to 256 characters.

    If the expanded Windows SharePoint Services file name contains invalid characters, or if the expanded file name or URL is too long, an error will be logged in the application event log and the message will be suspended. The error and the message state will also be visible in Health and Activity Tracking (HAT).

  9. Asif Azad says:

    I have the same problem with the Macro %FileName%.

    But the links

    ( http://msdn.microsoft.com/library/en-us/BTS06Operations/html/1ff50fb8-7ba0-47b8-9476-d57413989346.asp?frame=true )

    you gave have been replaced ( or not available ). So please can you give me alternative links ..??


    Asif Azad