Why custom macros
Macros on a send port is a neat feature, but it is too little, it cannot handle needs that are more specific.
Today we use the “standard” way of changing the system context property ReceivedFileName in a pipeline component and then using this via the %SourceFileName% macro.
This is of course a solution but this makes it hard for none initiated persons to really know what value to expect.
Description
The component, which must be used on a send pipeline, uses RegEx to extract all custom macros from the filename specified on the adapter configuration. It also uses RegEx to extract custom parameters.
Most of the custom macros, allows you to add custom input.
Available macros
%DateTime(?)%
%ReceivedDateTime(?)%
%FileDateTime(?)%
%FilePattern(?)%
%FileNameOnly%
%Context(?)%
%Folder%
DateTime
The %DateTime(?)% macro allows you to use use any part of the current DateTime. In short the component uses DateTime.Now.ToString(?), and the input to this macro is used as input to the ToString function.
Examples
%DateTime(%d)%, current day number
%DateTime(yyyy)%, current year
%DateTime(MM)%, current month
The component does not check to see if it is a valid format.
ReceivedDateTime
%ReceivedDateTime(?)% macro works exactly as DateTime macro, with the difference that the date is picked from system context property AdapterReceiveCompleteTime instead.
AdapterReceiveCompleteTime is the date and time when BizTalk picked up a specific message.
Remember that tracking must be enabled for this property to be present.
FileDateTime
%FileDateTime(?)% macro works exactly as DateTime macro, with the difference that the date is picked from system context property FileCreationTime
This is the date when the incomming file was created on disk. Should also work with FTP but I have not tested it.
FilePattern
%FilePattern(?)% macro allows you to use a RegEx expression on the Received filename. What the component does is to return the group items found on an expression match (please read up on RegEx if this is confusing)
Example
If we take the macro expression %FilePattern(^.{3}(.{3})([0-9]+))% and apply it to the file name NOTYES12345Exclude.xml, we would get the returned result YES12345.xml
That is because the expression have 2 groups specified (.{3}) and ([0-9]+). The first group extracts the 3 first chars and the second expression extracts all numbers after these 3 initial chars. Everything else is excluded.
TIP. If you wanted to switch the location, you could use different macros with different expressions.
Context
The %Context(?)% macro allows you to use a any context property value. To make the filename as small as possible only prefixes are used/allowed. So instead of using something like %Context(http://schemas.microsoft.com/BizTalk/2003/system-properties#Property)% we use the abbreviation %Context(BTS.Property%)
The following standard context abbreviations are possible
There is also a possibility to use one (1) custom prefix. I have used the prefix CST for all none Microsoft properties.
So if you have a custom context property you want to use, use the following syntax.
%Context(CST.Property%)
What the component will do when it finds a custom context macro is to go through all context properties that are not MS specific and return the value from the first property found with the name specified.
This means of course that this is a little bit riskier, you could possible pick up the wrong value. So only use this if you know that your context name is unique amongst the other none MS context properties.
Folder
Folder is a simple but helpful macro as a common requirement is to put a message in a specific folder depending on a date. Let’s say a file was created 2017-01-15. Then the requirement would be that the file should be saved in a structure like bellow.
Year
∟ Month
∟∟ Day
The folder macro simply inserts a back slash in its place. The component makes sure that the folder structure exists or creates it if it does not.
Example
If the URI is c:\integrations\int0010\ and the current date is 2017-05-04 and the macro expression %DateTime(yyyy)%%Folder%%DateTime(MM)%%Folder%%DateTime(dd)%%Folder%message.xml is used, then the final folder location would be c:\integrations\int0010\2017\05\04.
This of course does only work for the file adapter.
The code for the pipeline and pipeline component can be downloaded from here