BizTalk Message Archiving Pipeline Component : Atomic-Scope

Macros

Macros are a powerful feature in the BizTalk Message Archiving Pipeline Component in that they allow the filename of the archived message to be created at runtime, based on Context-Properties of the message. Any Context-Property set by a specific adapter or by message processing components (such as the Xml Disassembler, EDI Disassembler or MIME/SMIME Encoding components), or internal message properties can be used in macros, allowing you to create complex custom filenames at runtime.

Using Macros

Macros are defined using the percent character (%) at the beginning and end of the macro. For example, if you wanted to include a date and time in your filename, simply use the DateTime macro as follows - %DateTime%.

The component supports the use of macros in either the Archive Directory or Archive Filename properties.

Single Macros

Macros can be used either on their own or in combination with other macros. As a simple example, the macro %FileReceivedFileName% can be used on messages received via the FILE adapter in the Archive Filename property to archive the message with its original filename, as follows:

If we now configure BizTalk to retrieve a message called 'TestArchivingComponent.xml' via the FILE adapter, the message will be archived with the following filename, based on the properties we specified above:

Macros can also be used in the Archive Directory property, allowing the Message Archiving component to save the message to a custom directory structure. If you wanted to save all messages coming from a specific port for example, you may configure the component as follows - notice the %PortName% macro in the Archive Directory property:

If we get BizTalk to retrieve the same 'TestArchivingComponent.xml' message via the FILE adapter configured through a Receive Port called ArchiveTest, the message will be archived to:

Notice that the macro %PortName% has been replaced with the actual name of the Receive Port 'ArchiveTest' taken from the message context.

Given sufficient previledges, the Message Archiving component will create the necessary directory structure on a local drive, UNC share or mapped-drive.

Multiple Macros

Multiple macros can also be used to build complex filenames, by chaining macros together in either the Archive Directory or Archive Filename component properties.

For example, suppose you are receiving an inventory file from a customer's FTP server at hourly intervals. You want to archive each file to the same directory, with a timestamp included in the archive filename to indicate when the message was received. You could use the following chain of macros in the Archive Filename property to achieve this requirement:

This chain of macros will create an archive filename based on the original filename as received from the FTP server, including the date and time that the message was processed by the archiving component. Here we are using the macros 'FtpReceivedFilename-FilenameOnly' and 'FtpReceivedFilename-ExtensionOnly' to help us break apart the original filename so that we can insert the date and time.

If we now configure BizTalk to retrieve an inventory file called 'HourlyInventoryFile.xml' every hour over the FTP adapter, the messages will be archived with the following filenames, based on the properties we specified above:

Notice that the original filename remains the same, but the hour element of the date/time increases by an hour for each file (shown in bold).

Multiple macros can also be used in the Archive Directory property. Continuing with the example above, consider if we were now receiving new hourly inventory files from a second customer over FTP and we want to make a distinction in our archive directory structure as to where these files originated. We configure the Receive Port (called 'Hourly Inventory Files') to have two Receive Locations: 'Contoso Hourly Inventory Files - FTP' and 'Northwind Hourly Inventory Files - FTP'; our second Receive Location retrieves messages via FTP from our new customer, Northwind.

To acheive this distinction in our archive directory structure, we simply need to configure the Archive Directory property to include the %PortName% and %InboundTransportLocation% macros which are expanded to the Receive Port name and Receive Port Location name, as follows:

If we now enable the two receive locations and allow the system to collect a number of inventory files from both customers, we see several archive files - again, you will see that the original filename remains the same, but the hour element of the date/time increases by an hour for each set of files:

This has been a brief introduction into the power that macros can introduce into your archiving strategy. The following sections detail the various macros that are provided 'out-of-the-box' with the BizTalk Message Archiving Pipeline Component.

User-Defined Macros

User-Defined Macros allow developers to create their own macro's from Context-Properties defined in custom Property Schemas. User-Defined Macros are defined in Macro Definition files, Xml files that are loaded by the Archiving Component at runtime.

Creating and Configuring User-Defined Macros - An Example

In the installation directory, you will find a sample Macro Definition file called 'SampleMacroDefinitions.xml'. Copy this file and rename as 'SalesOrderMacroDefinitions.xml'.

Open the new Macro Definition file 'SalesOrderMacroDefinitions.xml' and overwrite the sample definition with details taken from your own Sales Order Property Schema:

In the example above, on lines 6 & 10 we have created two new macros: SalesOrderId and CustomerAccountId. These two macros reference the Context-Properties SalesOrderId and CustomerAccountId in the namespace http://schemas.atomic-scope.com/orders/sales-order-properties (the fact that the macro and context-property names are the same is irrelevant, the macro name can be whatever you want it to be). These context-properties correspond to a custom Property Schema that exists in our fictional SalesOrderProcessing BizTalk project.

In a moment we will configure an instance of the BizTalk Message Archiving Pipeline Component in the Resolve Party stage of a Receive Pipeline; then, when Xml sales orders are received, the Xml Disassembler component will promote the Sales Order Id and Customer Account Id values into the message context. The archiving component in the Resolve Party stage will read these two context properties and archive each sales order message to directories corresponding to the Customer Account Id, with the Sales Order Id as the filename.

To use the new Sales Order Macro Definition file, we need to reference it from the BizTalk Configuration file btsntsvc.exe.config so it can be used by the Archiving Component; the configuration file can normally be found in the BizTalk installation directory. Open the .config file and add a new appSettings section and key/value pair as shown below on line 4. Note: your configuration file may look slightly different to the example shown below.

The Archiving Component looks for key/value pair with a key that begin 'AtomicScope_MacroDefinitionResource_'. You must therefore always start your macro definition keys with this text - the wording you provide after this text is entirely at your discretion. If you do not use this text, the Archiving Component will not load your custom macro definition files and the macros you have defined will not be available for use.

Once you have added key/value pairs pointing to the location of your new custom macro definition file, restart the BizTalk Host Instance on which the Receive Location or Send Port is running to allow these changes to be registered within the BizTalk runtime.

We can now configure the Archiving Component in the Resolve Party stage of our Receive Pipeline to use this these two new macros. Notice how we are using the %CustomerAccountId% macro in the archive directory property and the %SalesOrderId% macro in the archive filename property:

Finally, we test the changes that have been made by passing a number of sample Sales Order messages from our two customers - Contoso and Northwind - through the pipeline. The custom properties will be promoted into the message context and the Archiving Component will evaluate these two new macros into their corresponding context-properties, archiving the messages to the correct locations on the filesystem, as shown below: