File renaming patterns

This chapter describes the use of file renaming patterns when you create or manage partner and application deliveries of the type:

• FTP external
• FTP embedded
• File system

For each of these delivery types, you can select the option to define a naming construction pattern for the new generated file names and for automatic duplicate file naming. To configure the resulting file naming, you must enter a naming pattern in the Pattern field.

The information in this chapter also applies to fields you complete for the:

• Message Handler file renaming action
• PeSIT delivery configuration

The values you can enter in the Pattern field vary depending on the use case.

Delivery exchange and Message Handler rename patterns

You can enter any combination of the following elements it the Pattern field for Delivery exchange file naming and duplicate handling, and Message Handler file renaming actions:

• Literal strings
• %metadata name% – You can use any metadata attribute associated with the FTP or File System delivery. You cannot use Custom attributes.
• $filename$
• $extension$
• $timestamp$– Where timestamp is a shortcut for SimpleDateFormat string ‘yyyyMMddHHmmssSSS’.
• $sequence$ – This is a monotonically increasing counter. A different counter is maintained for each delivery exchange. A Message Handler rule uses a single global counter.
• $any legal Java SimpleDateFormat string$

Examples

The incoming file name (before any renaming takes place) is represented by the tags $filename$ and $extension$. For example, an incoming file named TestFile1.txt would have the name defined by the tags:

• $filename$ = TestFile1
• $extension$ = .txt (note that the dot is included)

You could enter the following patterns in the Pattern field to obtain the following results.

Delivery exchange duplicate file name patterns

In the Filename tab for FTP and File System exchanges you can set Duplicate file renaming by entering a renaming pattern in the Pattern field. The patterns that you can enter in this field are similar to the renaming patterns listed above, with the following differences:

You must include $filename$.

You must enter at least one of the following elements, in order to ensure that a unique name is generated for the duplicate:

• $sequence$ – This is the sequence number calculated from all delivery file names handled on all deliveries
• $timestamp$
• $filesequence$ – This variable is only allowed in the duplicate file naming case (not the file naming case above). It is calculated from only the file names handled on the specific delivery where you set the pattern. It is recommended that you use $sequence$ instead of $filesequence$ because $filesequence$ consumes greater processing resources.
• $any legal Java SimpleDateFormat string$

How Activator handles file and duplicate file naming

The Activator trading engine sets the filename and extension values immediately before it parses the name value for any pattern-based naming modification. This means that file renaming is based on the current filename value, immediately before the renaming operation. When the filename value is changed during a renaming operation, the new file name is used for the next renaming operation that occurs in the message flow. So in the case where the file name is changed, it is no longer the original incoming filename value that is used in the next rename operation, but the actual current value.

Example:

1. A pickup consumes the file My.txt.
2. You have configured the Message Handler with the File Rename Rule Pattern $filename$File$extension$.
3. Filename result = MyFile.txt
3. A file system delivery is configured with the File Rename Pattern $filename$$extension$.backup .
4. Filename result = MyFile.txt.backup
4. Suppose Activator detects a filename duplicate - the file MyFile.txt.backup already exists at the delivery location. You have configured the file system delivery with a Duplicate Rename Pattern $filename$_$timestamp$$extension$.
5. Filename result = MyFile.txt20130215113703512.backup

About dots (.) in extension tags

In renaming patterns, the existing metadata element ConsumptionFilenameExtension always includes the dot.

If the $extension$ tag did not have the dot, there would be many situations when you would have to enter a pattern such as $filename$.$extension$, which produce defective results when the incoming file name had no extension at all.

Examples:

Incoming file=FileWithoutExension with pattern $filename$.$extension$ is renamed FileWithoutExension.

Incoming file=FileWithoutExension with pattern $filename$.$extension$.backup is renamed FileWithoutExenstion..backup. (Note the duplicate dot in the result).

To prevent this error, the extension tag includes the full extension, if any, including the dot. Therefore $filename$$extension$ tags work in all cases, without problem.