Using the Naming Macros

Automator offers a number of naming macros that can be used to name files and tables that are being exported, moved, copied and so on. They can also be used to add information when performing distributions or even when using scripting. The macros can be used individually or in combination with one another.

Note: Some of the naming macros may not be valid under certain conditions (for example, some macros are only available when using scripts), so until you are well acquainted with the product, use the Insert Macro icon naming macros.zoom80 to ensure that you select macros that are valid for the situation.

The following naming macros are available:

Macro		Symbol	Result
Year (4 digit)		&[yyyy]	4-digit year (for example, 2007)
Year (2 digit)		&[yy]	2-digit year (for example, 07)
Month		&[mm]	Month
Day		&[dd]	Adds the day to the file name as a two digit numeral, for example, 09 for the ninth Day
Hour		&[hh]	Hour
Minute		&[mi]	Minutes
Second		&[ss]	Seconds
Quarter		&[qtr]	1-digit quarter of the calendar year: 1 for dates in January: March, 2 for dates in April: June, 3 for dates in July: September, 4 for dates in October: December.
Day of Year		&[dayofyear]	3-digit day of the year in range 001-366.
Previous Day		&[dd.-1d]	2-digit value in the range of 01-31.
Previous Month		&[mm.-1m]	2-digit value in the range of 01-12.
Previous Year		&[yyyy.-1y]	4-digit year (referring to previous year).
ISO Year		&[isoyear]	4-digit year corresponding to the ISO-8601 week in which the date falls.
ISO Week		&[isoweek]	2-digit week of the year (range 01-53) as defined in ISO-8601. Note that it's possible for a date in late December to actually fall in week 01 of the following year. Likewise, it's possible for a date in early January to fall in the last week (52 or 53) of the previous year.
ISO Day of Week		&[isoday]	1-digit day of the week as defined in ISO-8601, namely, Monday=1, Tuesday=2, Wednesday=3, ... Sunday=7.
Summary Name		&[summary]	Name of current summary. This option becomes available when a summary is selected for export. For multiway export by tables, if all summaries are selected, the system will apply the summary name for the table name by default. As for multiway export by files, no extra changes are needed because the file name is set to the summary name. Note: This macro is not available when all or more than one load plan is selected.
Filter Name		&[filter]	Name of current filter. Empty if no filter is current.
Measure Title		&[measure]	Name of current measure. Empty if no measure is current.
Key Value		&[keyvalue]	Value of a key field.
First Value of Field		&[firstvalue.value name]	Name of the first value in the selected field. See the Select a Field Name dialog for more information. Note: This macro is not available when all or more than one load plan is selected.
Input File Location		&[input]	Full path and filename of an input file. To specify multiple input files use the convention &[input.1] &[input.2] etc. If there are more &[input]s than input files, the extra ones are replaced by empty strings. When importing from a database there are no input files, so all &[input]s are replaced by empty strings.
Input File Name		&[inputname]	Filename of an input file. To specify multiple input files use the convention &[inputname.1] &[inputname.2] etc. If there are more &[inputname]s than input files, the extra ones are replaced by empty strings. When importing from a database there are no input files, so all &[inputname]s are replaced by empty strings.
Output File Location		&[output]	Full path and filename of an export file. To specify multiple output files use the convention &[output.1] &[output.2] etc. If there are more &[output]s than export files, the extra ones are replaced by empty strings.
Distribution Source file path		&[source]	Full path and filename of a file that is being distributed via a distribution action. If multiple files exist, this macro will expand all names and concatenate them using a semicolon.
Distribution Source file path (Advanced)		&[source.option]	The option specifies which part of the path to return, i.e., dir for directory, file for filename with extension, name for filename alone, ext for extension.
Job Number		&[jobid]	Job number
Job Log		&[joblog]	Full path and filename of the Job Log
Process Name		&[process]	Process name
Date Format		&[date.<date increment>.<output format>]	Subtracted date; <date increment> could be -1d, +1d, -1m, +1m, -1y, +1y, and <output format> could be yyyyMMdd, yyyy-MM-dd, etc. The output format is case-sensitive. For a full list of supported format specifiers, click here.
System-Wide Counter		&[counter]	System counter. Automatically increments with each use A?a??a?? counts across all jobs in all processes.
Load Plan		&[loadplan]	Name of load plan selected.
Item Addressing (Advanced)		&[item.xpath]	A specific element or attribute of a job log input or output item. The XPath following the macro name is an XPath expression describing exactly which node is to be returned. Note that these macros are only available for scripting and distributions. In most cases they will be used in scripting to assist in navigating through the job log. They cannot be used for file or table naming.
Item File Path		&[source]	Full path of an item.
Item File Directory		&[source.dir]	Full path of item directory.
Item File Name		&[source.file]	File name of an item.
Item File Name (no ext.)		&[source.name]	File name of an item with no extension.
Item File Extension		&[source.ext]	Extension of item file.
Item URL		&[source.uri]	URL of an item.
Item Title		&[item.title]	Title of an item.
Item Description		&[item.description]	Description of an item.
Item Addressing Examples		&[item.title] &[item.description] &[item.sort] &[item.filter] &[item.summary] &[item.totals/@record_count	Returns the auto-generated item title Returns the auto generated item description Returns the sort, if specified Returns the filter, if specified Returns the summary, if one exists Returns the record count
Time Intervals	Calendar Year	&[yyyy]	4-digit calendar year
	Calendar Half-year	H&[halfyear]-&[yy]	The calendar half-year in which the date falls, where each half-year is defined as six calendar months.
	Calendar Quarter	Q&[qtr]-&[yy]	The calendar quarter in which the date falls, where each quarter is defined as three calendar months
	Calendar Month	&[monthname]-&[yy]	The calendar month
	Calendar Week	W&[week]-&[yy]	The week number
	ISO8601 Year	&[isoyear]	The year corresponding to the ISO week in which the date falls.
	ISO8601 Week	&[isoyear]-W&[isoweek]	The ISO week in which the date falls.
	Fiscal Year	FY&[fendyear]	The fiscal year expressed as the calendar year of the first day of the fiscal year in which the date falls
	Fiscal Half-year	FH&[fhalfyear]-&[fendyy]	The fiscal half-year in which the date falls
	Fiscal Quarter	FQ&[fqtr]-&[fendyy]	The fiscal quarter in which the date falls.
	Fiscal Period	FP&[fperiod]-&[fendyy]	The fiscal period; either a calendar month or a 4- or 5-week period, depending on the type of fiscal year
	Fiscal Week	FW&[fweek]-&[fendyy]	The fiscal week number in which the date falls.

The naming macros are available in the following locations:

Job Disposition Settings: Use the naming macros here to name job logs that have been moved.
Copy Distribution Action: Use the naming macros here to name copies of files generated by a distribution.
Move Distribution Action: Use the naming macros here to name files that have been moved via a distribution.
Email Action: Use the naming macros here to provide a subject line for an email distribution or alert.
RSS action: Use the naming macros here to provide a title and description for an RSS distribution or alert.
Default Job Log Disposition: Use the naming macros here to assign new names to the job logs when moving them.

Note: The naming macros can also be used when scripting, for example, when using the Item.ExpandMacros method. See the UserScripting Help file for additional information. To use the naming macros in email body fields and NT Event Log Message fields, right-click and choose Insert.

Utilizing naming macros

When viewing a field for which you can select a naming macro, click the adjacent Insert Macro icon to view the naming macro drop-down list.
Select the desired naming macro from the list.

Syntax checking of macros

In the Export Wizard and the Portable Report Settings dialog, if the file name contains a macro (or macros), Automator performs a series of tests to be sure that the macros are well-formed. For example, the following conditions are detected and reported as errors:

Unknown macro names, for example, &[fred]. Such macros will not expand at runtime.
Parameterized macros having ill-formed parameters, for example, &[yyyy.+1q]. Such macros will expand to empty at runtime.
Macro names that are not appropriate in the context of the export in question. For instance, &[filter] makes no sense when publishing a PRF file.
Ill-formed macros. For example, a macro prefix (&[) without its matching suffix (]), or a macro embedded within a macro for example, &[fil&[dd]ter].