FILE & FTP adapter: Manipulating File Names

Published 18 June 04 06:58 PM | christof claessens

Very frequently, in the BizTalk Server newsgroups, I answer questions related to filenames used by the BizTalk Server FTP and FILE adapter. More in particular it seems that for many people it is hard to figure out:
- how to change the FILE/FTP adapter's output file name
- how to acces the FILE/FTP adapter's input file name

Let's change this and dive into the subject a little deeper:
...starting with the more easy thing: the FILE adapter's input and output filename.

When the FILE adapter receives a message, it promotes context on the message that contains information about the orginal filename. That context is accessible in:
  • a custom pipeline (where you'll have to program)
    • use the IBaseMessage you get passed by the pipeline framework
    • that interface provides you with a context property, which you can use to read promoted properties from
    • to give you a feeling, here's a (non-tested!) example:

      public IBaseMessage Execute(IPipelineContext pc, IBaseMessage inmsg)
      //following namespace contains the FILE adapter properties:
      const string FILEadapterTargetNamespace = "";

      // retrieve the inbound file name that was promoted by the FILE adapter:
      string sourcePath = inmsg.Context.Read("ReceivedFileName", FILEadapterTargetNamespace ) as string;

      return inmsg;
  • an orchestration (here you have intellisense)
    • drop in there an expression shape
    • you can access the context of you inbound message, using the context syntax (regular brackets after the messagename with in between the propertyname)

The FTP adapter does same thing upon receival of messages but obviously uses another context property to promote that information on.
It's namespace:
It's file name context property: ReceivedFileName

So far on the receival side of things, but what about sending? When sending files, the FILE and FTP differ somewhat in their approach...
Let's start again with the FILE adapter, where you basically have two options when you want to specify the outbound file name:
  • Using a static port: specify the outbound file name using one of the supported macro's

    This one's easy: the FILE adapter offers you some macros that you can use when binding the BizTalk Server messaging port.
    MSDN explains this very well, so I will not go into any details further here... (In addition I remember Jan already posted on this subject as well!)
  • Using a dynamic port: specify the outbound file name by setting context on the outbound message

    Setting context can be done both in a custom pipeline component as well as in an orchestrations expression shape. In any case, when using a dynamic send port in an orchestration, you should set the outbound URL. This can be done in any expression shape (you have intellisense for this). The engine will parse the URL and based upon the prefix (file:// or ftp://) it will use the correct adapter. In addition you may add other context as well (for example specifying the message's retry count).

    Setting context using a custom pipeline component is perhaps less straight forward, so let's look into this using a little sample:

    IBaseMessage Execute(IPipelineContext pc, IBaseMessage inmsg)

    //following namespace contains the FILE adapter properties:
    const string FILEadapterTargetNamespace = "";

    // set the the outbound file name for the FILE adapter:
    inmsg.Context.Write("ReceivedFileName", FILEadapterTargetNamespace , "myOwnNewFileName.xml");

    return inmsg;

So... that's it :-) Easy huh! The previous method can as well be used when having a static send port! If you explicitly set the filename in the context the FILE adapter will take this into account and won't use the "default" values specified for that BizTalk Server messaging port.

Now how does this work with the FTP adapter you might wonder? Unfortunately the FTP adapter does not have any macros you can use to set the outbound file name. However both the approach using the dynamic port as well as setting context manually works very well.

For example, inside an orchestration, I might set the location of a dynamic send port like this:

//Set dynamic ports location:
orchprtSndMyMessagePort(Microsoft.XLANGs.BaseTypes.Address) = "ftp://myserver/mydirectory/myfilename.xml";

//Set context on the message you want to send:
msgMyMessage(FTP.UserName) = "myFTPUsername";
msgMyMessage(FTP.Password) = "myFTPPassword";
msgMyMessage(BTS.RetryCount) = 20;
msgMyMessage(BTS.RetryInterval) = 2;

As illustrated, you'll need to specify the username and password for the connection as well. All together I guess this is not a bad approach at all. (Could be more user friendly but once you know, it dóes makes sense, right? In the end, évery adapter gets it's configuration from the message context!)

Very nice, very nice... but, what if you want to be able to transmit files in a particular order, or what if I want to grasp the return value from the FTP adapter's send operation?

There's no way you can grasp the return value of the FTP operation directly. Such kind of things is completely hidden by the adapter itself. BUT there's a way that allows you to know inside your orchestration wether the transmit operation succeeded. This is implemented using a switch on the level of your orchestration's send port, called: "DeliveryNotification". If set to "Transmitted", this will ensure that your orchestration stops working, until the adapter has succesfully transmitted the message. It's the same switch that allows you to send your messages in-order. In addition: if the message fails, an exception will be thrown of type: "XLang.DeliveryFailureException".

So far for files :-) If you have any further questions related to custom pipeline components... watch this blog! I will come back on this subject, showing you some very cool things!! (Obviously the newsgroups are still there as well.)

Have a nice day!
Filed under:


# Christof Claessens said on June 21, 2004 07:02 PM:

Hi Martijn,

Your orchestration should STOP at the point of your send shape if the deliveryNotification was set to "transmitted". If not, please send me your scenario and I'll validate upon that.

(This does not mean that your orchestration stops working entirely of course!! If you have several branches running, these will stil be running in parallel.)

I know about the succeeded operator, which has a slightly other purpose...

Best regards!

# Girija said on June 25, 2004 03:36 AM:

Our client wants our xml to have
<element/> instead of
when the lement in our output file is empty.
How do I do it in Biztalk?

Biztalk seems to put both the tags when the elements are empty, by default.


# Christof said on July 5, 2004 01:48 PM:

Hi Girija,

actually, the real "meaning" of those two constructs is exactly the same. The first one is just an XML shortcut for the second one. If they require you to send tags like the first, they do not comply with the XML standard. However, that still doesn't solve your problem. As for now, I'm not aware of any "switch" that allows to do this out of the box. (And to be honest: they should not provide this!) A custom pipeline component working with some XMLReaders and writers should do the job :-)

best regards,

# Bovey King said on July 16, 2004 12:12 PM:

It does really help. I tried to figure out how to get ftp file name for a couple of days.

# José Ignacio said on August 3, 2004 02:14 PM:


i'm trying to configure a ftp dynamic port and in my custom pipeline component i want to modify the context's properties of the user and password but I always receive this error

"The Messaging engine failed to process a message submitted by adapter:BizTalk HTTP Receiver Source URL:/httpReceive/BTSHTTPReceive.dll. Details:Could not find a matching subscription for the message. . This error occurs if the subscribed orchestration schedule or send port has not been started, or if some of the message properties necessary for subscription evaluation have not been promoted. Please refer to Health and Activity Tracking tool for more detailed information on this failure

i can't debug my custom component when the send port is dynamic, when the send port is static everything is okay. any idea?...

thank for your help


Biztalk's fan club

# Christof Claessens said on August 3, 2004 04:27 PM:

Hi José,

I'm not sure about your story... Why can't you debug your custom pipeline component if the send port is dynamic? Just attach your debugger (VS.NET) to the BTSNTSvc.exe process. You should be able to attach without too much trouble. The error you receive is because the pub/sub engine is not able to match your message with any active subscription. What does your send port exactly do please?

I would strongly advise you to post technical issues to the BizTalk Server public newsgroups, where a lot of people will be happy to assist you.

Best regards,

# rajesh said on February 24, 2008 10:41 PM:

In the FTP adapter case, with out using orchestrations  how it is possible to set the outbound filename.

# latch said on February 25, 2010 05:56 AM:

Is there any way that you can change the ftp port behaviour so that you can dictate the name of the temporary file is when using the temporary folder option. We're currently working with an FTP Server that will not accept the curly brackets in the filename which seems to be the default.

# buy clenbuterol said on June 9, 2011 12:45 AM:

Pens&#233; que iba a comentar y decir que el tema limpio, &#191;lo hacen por ti mismo? Es realmente impresionante!

# Manufacturers of lamps for the home said on August 25, 2011 04:00 PM:

I know this isn’t precisely on topic, however i've a web page using the same program as properly and i am getting troubles with my comments displaying. is there a setting i am missing? it’s attainable you could help me out? thanx.

# shore excursions in St.Petersburg said on August 30, 2011 06:25 AM:

My associate and I really enjoyed studying this blog submit, I used to be simply itching to know do you trade featured posts? I am always trying to find someone to make trades with and merely thought I might ask.

# private guide in Saint-Petersburg said on September 1, 2011 07:59 AM:

Now you've gotten your new web site and you’re eager to begin making some sales! But, how will you make gross sales if you happen to do not need high volumes of holiday makers to your website?

# outdoor lighting manufacturers canada said on September 2, 2011 12:04 PM:

Just killing some in between class time on Digg and I discovered your article . Not usually what I choose to examine, nevertheless it was absolutely worth my time. Thanks.

# производители металлоконструкций said on September 12, 2011 04:09 PM:

Manufacture and installation of steel Steel Company " SMK Engineering " is widely used in many fields of agriculture, industry , logistics, entertainment and sports.Our steel with various types of coatings can be used as livestock and poultry farms, warehouses, shelters for the equipment, handling sites, industrial plant , shopping , sports and entertainment pavilions.Reasonable prices , excellent performance of construction works , manufacturing deadlines , 3 -year warranty and service for the duration of operation - are the main advantages of our company. In addition, we propose a frame- tent reconstruction projects and farm sheds in the presence of supporting structures at the lowest prices .  

take a chance on

# appliance repair said on September 23, 2011 04:39 PM:

Vielen Dank für die tolle Information! Ich würde nicht anders entdeckt haben!

# DSLR-A900 said on November 16, 2011 08:26 AM:

außergewöhnliche Website senden. Ich werde Lesezeichen und Check-Out viel häufiger. Ich mag die Website-Templates

# Beetafriele said on June 5, 2012 03:01 AM:

composed by hsm 2012-06-04

# ordilielami said on July 27, 2012 09:26 PM:

Schätzungsweise 35 Strukturen haben  schon   vor kurzem   möglicherweise   vom  innerhalb der Flamme, und  und so   die sich   geworden  sind bereits getan. <a>longchamp taschen</a>

Arizona State Forestry Division entsandt zwei Wasser Ausschreibungen  wie auch,   mit   Progressive  Mexiko, welche  knowning dass   manchmal   diese  Ankunft  eine  -10 Jetliner dass  dass viele  kann sehr lag  die tatsächliche  100 Meter breiten, Meile-lange  path   aus aller   sowie  wahrscheinlich Wasser.

<a>longchamp schweiz</a>

Feuer-Chefs  ganzen   Besser   obendrein  Arizona bestellt weitere Elite-Besatzungen, Motoren und  und danach   in   Drehen   in etwa  mit Albuquerque, wo Regisseur Kenan Jaycox genannten Ressourcen sind  gerade sind  wurden bereits nahenden voll ausgelastet.

# weareeThatt said on August 31, 2012 04:00 AM:





# GafeWrofe said on September 5, 2012 07:19 PM:





# Absordreibe said on September 6, 2012 05:58 AM:





# Zesemensush said on September 6, 2012 10:12 AM:





# myncWrismic said on September 19, 2012 05:18 AM:





# Jimmyad8pt said on November 6, 2012 03:31 AM:

geedn<a href=> james harrison jersey </a>

svsvo<a href=> jason hanson jersey </a>

ltxdx<a href=> benjarvus green-ellis jersey </a>

bhvgx<a href=> benjarvus green-ellis jersey </a>

hwpoo<a href=> charles woodson jersey </a>

# VoneeunuriPep said on November 8, 2012 12:12 AM:

FgtzULMS  jxfyCNUya  mwyvcizccz  IEQjVxgtc zfuddo  XewVFYLFsuh AktmIPIX  wtzvTEJob LxdiGFXN  kkbiWKKlj

# said on November 8, 2012 06:40 AM:

Do you have a spam problem on this website; I also am a blogger, and I was curious about your situation; we have developed some nice procedures and we are looking to swap solutions with others, please shoot me an email if interested.

# Okeefe said on February 10, 2013 10:52 AM:

What's up, of course this post is genuinely nice and I have learned lot of things from it regarding blogging. thanks.

# Saxon said on February 19, 2013 03:57 PM:

Good day! Would you mind if I share your blog with my zynga group?

There's a lot of folks that I think would really enjoy your content. Please let me know. Cheers

# Locke said on April 7, 2013 09:22 PM:

It's going to be ending of mine day, but before end I am reading this impressive piece of writing to increase my knowledge.

# said on April 12, 2013 06:32 AM:

Hello, just wanted to tell you, I loved this blog post. It was inspiring. Keep on!

# Shay said on May 7, 2013 06:11 PM:

Hurrah, that's what I was exploring for, what a data! present here at this blog, thanks admin of this site.