A macro variable is a string enclosed in a set of percent signs (for example, %inbox%), used to indicate substitution of other data. You can use macros for many reasons, including, for example, defining a unique file destination, indirectly referencing directory locations (for inboxes, outboxes, etc.), or passing information to an Execute On Successful Send command.
Types of macro variables
Macro variables are classified in one of three ways:
- Reserved Macro Variables: Variables that are predefined within the Cleo Harmony product. See the table below.
- Custom Directory Macro Variables: Directory variables that are defined by the Cleo Harmony user. See Specifying Default Host Directories for more information about specifying Custom Directory Macro Variables.
- Custom Macro Variables Defined as System Properties: Variables that are defined as name=value pairs using the Java ‘–D’ Command Line parameters (see Bootstrap Configuration for further information) or are specified in the conf/system.properties file. Note that Custom Macro Variables are resolved after Reserved Macro and Custom Directory Macro Variables and therefore cannot be used to override those variables.
The following table outlines the macro variables (both reserved and custom) and the various contexts in which they can be used.
|Source File||Destination Files||SYSTEM Command||Default Host Directory||Default Local User Active Directory||Default Root Directory||Windows/Unix Folders||Custom Variable||Execute-On||Pre/Post Command||LCOPY Archive||Accessible through API||Directories Only||Banner/Welcome Message|
|custom directory variable||X||X||X||X||X||X||X||X||X||X||X|
%sourcefile%) is simply passed through. Further, if a macro is used that is not supported within a particular context (for example, referencing
%crc%within a Destination File context), it will simply be passed through as well.
It is possible to add general variables to the conf/system.properties file and use them within the contexts outlined in the table. To add a general variable to conf/system.properties, the syntax is:
varName=replacementText. For example, if conf/system.properties has the following:
myvar=hello, the usage would be
%myvar% in the desired location.
- Unlike other macro variables that are case-insensitive,
system.propertiesmacros are case-sensitive.
- After adding a macro to conf/system.properties, the service must be cycled before the macro can be processed.
Macro variables are valid in certain contexts. The following describes the various contexts in which macro variables are valid. Not all macro variables are valid in all contexts.
- Source File
- Applies to the "source" values of LCOPY, LDELETE, LREPLACE, PUT, and CHECK commands (Cleo Harmony and Cleo VLTrader applications only). Macros are also supported for the HTTP "filename" parameter and the "source" values of the GET commands for FTP and SFTP protocols only. Macros are not supported for the "source" values of GET commands for other protocols or the DIR command.
- Destination File
- Applies to the "destination" values of LCOPY, PUT, GET, and CHECK commands (Cleo Harmony and Cleo VLTrader applications only). It also applies to default file names, as specified under the host AS2 tab (see AS2 Host: AS2 Tab), the host AS4 tab (see AS4 Host: AS4 Tab), the host ebXML tab (see ebXML Host: ebXML Tab), the host EBICS tab (see EBICS Host: EBICS Tab), and the Local HTTP Users HTTP tab (see Configuring access for HTTP host users). It also applies to the file destination, as specified under the host OFTP tab (see OFTP Host: OFTP Tab). The Destination File context also applies to macros that can be included within HTTP parameter/header values, as defined under the HTTP tabs for HTTP-based protocols (for example, AS2, ebXML). Also, this context applies to the
FileFormatparameter on EBICS GET command. See EBICS Command Reference. The Destination File context macro variables may also be used within the Subject header of the SMTP tab. Note that macros such as
%transferid%really only make sense for the file name--not the file path. However, macros such as
%mailbox%could make sense as part of the path.
- SYSTEM Command
- Applies to the SYSTEM command that can be run within the host actions (see Using operating system commands in actions).
- Default Directories
- Applies to the default inbox/outbox/sentbox/receivedbox, as specified under the host General tabs (for an example, see FTP Configuration). The
%host%macro variable is supported, but not
- In addition, the
%date%macro is supported, but the
%time%macro is not. Be careful using the
%date%macro in the default outbox because files in the date-stamped outbox subdirectory will not be sent if the send action occurs after midnight. Likewise, archiving entries in sentbox and receivedbox date-stamped directories will only occur for the current date.
- Default Local User Archive Directories
- Applies to the sentbox and receivedbox archive directories as specified under the local user host General tabs (for an example, refer to Configuring local FTP users). Both the
%mailbox%macro variables are supported in this context.
- In addition, the
%date%macro is supported, but the
%time%macro is not. Be advised that archiving entries in sentbox archive and receivedbox archive date-stamped directories will only occur for the current date.
- Default Root Directory
- Applies to the default root directory, as specified under the local user FTP tab, HTTP tab, and SSH FTP tab (for an example, refer to Configuring local FTP users). It also applies to the user home directory, as specified under the local user mailbox FTP tab, HTTP tab, and SSH FTP tab (for an example, see FTP Mailbox: FTP Tab).
- Windows/Unix Folders
- Applies to the UNC paths specified when you set up Windows/Unix folder access. See CIFS directories. Macros used in this context should always be UNC paths starting with two backslashes (\\). No other macros are supported within macros used in this context.
- Custom Variables
- Applies to the values that can be specified under custom directory variables on the General tab under Configure System Options. See Other system options for more information.
- Applies to the system commands that can be specified within the Execute On Successful Send/Receive/Copy/Check properties and the Execute On Fail property (system, host, or action level). See Advanced system options for information about the Advanced tab under Configure System Options for definitions of these properties. With regard to Execute On Fail command, when a command is executed as a result of a failed transfer (either on the client or the server), then all applicable macros are supported. When a command is executed as a result of a general system failure, then only
- Post/Pre Command
- Applies to the FTP properties Post Get Command, Post Put Command, Pre Get Command, and Pre Put Command, as specified under the FTP Host: Advanced Tab. This context also applies to the Post Put Command and Pre Put Command properties as defined in the SSH FTP Host: Advanced Tab.
- LCOPY Archive
- Applies to the archive directory that can be specified with the LCOPY Archive property (system, host, or action level). See Advanced system options for more information.
- Accessible through API
- Applies to macros that are available through
IactionControllerinterface of the API (if the API is licensed). Refer to the API javadocs for a description of this interface and the method that can be used to obtain a given macro value.
- Directories Only
- Applies in several places where only the custom directories macros or %inbox%/%outbox% are appropriate.
- Banner/Welcome Message
- Applies to the banner and/or welcome messages for the HTTP, FTP, SMTP, and SSH FTP servers. See Configuring Local Listener Responses.
Rules Regarding Macro Variable Use
Below are some general rules for macro variable use.
- Macros are identified by
cis one-to-many characters.
- Macro variables are case insensitive. You can enter them in lowercase or uppercase.
- You cannot place a
%within a macro variable.
- When a string contains macros to be resolved and a
%that is not tied to a macro, you must escape the non-macro
%%. After all macro substitution takes place, the software strips the extra
%, yielding the intended character sequence. For example,
LCOPY test.edi %%%date%_%index%is resolved to
?characters are not allowed within a macro name. Use other special characters with caution.
- When using the
%time%macros, it is your responsibility to ensure the formats for the date and time do not violate any file system naming conventions, for example, if the macros are being used to build a filename or directory.
- Macros are not allowed within a source filename that contains a
?, or regular expression. For example, in
%mailbox%is not resolved. However, in
%mailbox%is resolved because it is referenced in the source directory path and not the source filename.
- You can use macros multiple times within the same command. For
%index%, the same substitution value is used in all references within the same command. However, when you use either of these macros within the destination path of an LCOPY, and multiple files are being copied in one command, the following special rules are enforced:
- If these macros are used anywhere within the directory path, they are only resolved once within command.
- If these macors are used within the file token, they are resolved for each filename.
- Macros you use within a system command, either within the SYSTEM Command context or within the Execute-On context, can be used as part of the actual command or as parameters to a batch file.
- If the absolute path of the any of the files referenced in the macros contain embedded spaces (for example.,
Program Files\LexiCom\inbox\testHost\test.edi) it might be necessary to add double quotes to the macro specification(s) in the command in order for the command to be properly processed by the operating system. For example,
copy “%file%” “%file%.bad”.
- Special rules apply to using directory macro variables for example,
%outbox%,and custom directory variables.
- If you use these macros in a source file, destination file, custom directory variable definition, or an LCOPY Archive context, and the path is a non-URI path, they are replaced only at the beginning of the string. For all other contexts (for example, URI source/destination paths, SYSTEM commands), they are replaced anywhere in the string.
- Although allowed, you should not use directory macros should within a remote destination file context, as they reference local directory paths and are therefore nonsensical in this context.
- When preceding a path with a directory macro, you should place a file separator character (for example, ‘/’or ‘\’ between the macro and the subsequent path (for example,
- When using directory macros, care should be used so as not to create circular references (for example, host outbox references
- All directory macro variables reference their absolute paths.
Reserved Macro Variables
Below is the table of all reserved macro variables.
||References the system-level inbox/outbox/sentbox/receivedbox.|
||For sentbox/receivedbox fields where this option is available to select, this indicates that there should be no associated sent/receivedbox (rather than defaulting to the system values in the absence of a selection)|
||References the absolute path of the configured host or local user inbox.|
||References the absolute path of the configured host or local user outbox.|
||References the local file (including the absolute path) involved in the current operation. For PUT and certain CHECK commands,
Note: The CHECK command is only available in Cleo Harmony and Cleo VLTrader applications.
||References the source file name involved in the current operation. If the source file is local, and it is referenced in the Execute-On context, then the absolute path is included.|
||References the source file name base (everything up to, but not including, the last '
||References the source file name extension (everything from, and including, the last '
||References the destination file name involved in the current operation. If the destination file is local, and it is referenced in the Execute-On context, then the absolute path is included.|
||References the destination file name base (everything up to, but not including, the last '
||References the destination file name extension (everything from, and including, the last '
||Specifies the current date in the format defined in the
||Specifies a variant of the date as a value in either the past or the future. The '
||Specifies the current time in the format defined in the 'Macro Time Format' setting (system, host, or action level). See Advanced System Options for more information about this property.|
||Specifies a variant of the time as a value in either the past or the future. The '#' character specifies one or more digit values and the order of the +/- fields (h=hour, m=minute, s=second) dictates the order of the operation, however calendar rules still apply (e.g., if the operation causes the minute to wrap to the next hour then the hour value is automatically incremented). The MacroTimeFormat parameter variable is case-insensitive, however if it is specified with the +/- field(s), it must be specified as the last parameter. If it is not specified, the format defined in the '‘Macro Time Format'’setting (system, host, or action level) is used. See Advanced System Options for more information about this property.|
Specifies the usage of a daily host index value; often used to help guarantee file uniqueness. Each host's index is reset to 1 at the beginning of each day. It is incremented by one every time %index% is referenced.
The minimum number of digits in the index string is determined by the 'Minimum Number Of Macro Index Digits' setting of the of Configure System Options. See Advanced System Options for more information.
||The alias of the host involved in the current operation.|
||The alias of the mailbox involved in the current operation.|
||The status of the current operation. Returned status values are either "Success" or "Warning" (both denote a successful transaction) and "Error" or "Exception" (both denote a failed transaction).|
||The value of the computed CRC-32 associated with a transferred file. The CRC is computed only when 'Compute CRC on transfers' is on (see Logs for information about the Messages tab in Configure System Options). This feature is available only for Cleo Harmony and Cleo VLTrader applications.|
||The size of a transferred file in measured in bytes.|
||The value of the unique ID assigned to a transferred file. This feature is available only for Cleo Harmony and Cleo VLTrader applications.|
||The number of files received through within an action.|
||The number of files sent through within an action.|
||The full command syntax (only available for the Execute-On context of CHECK commands).|
||The date portion of the SOAP header's <eb:Timestamp> value. The format of the date is determined by the 'Macro Date Format' setting (system, host, or action level). See Advanced System Options for information about Advanced tab under Configure System Options for a definition of this property. This macro will only be resolved when used in the default file name.|
||The time portion of the SOAP header's <eb:Timestamp> value. The format of the time is determined by the 'Macro Time Format' setting (system, host, or action level). See Advanced System Options for information about Advanced tab under Configure System Options for a definition of this property. This macro will only be resolved when used in the default file name.|
These macros will only be resolved when used in the default file name.
||The current AS2-To value provided in the received message header. This macro will only be resolved when used in the default file name.|
||The current AS2-From value provided in the received message header. This macro will only be resolved when used in the default file name.|
||The current Subject value provided in the received message header. This macro will only be resolved when used in the default file name.|
||The AS3-To name of a client. This macro will only be resolved when used in the SITE command within an action to verify that the AS3 names are properly configured on the VersaLex AS3 server.|
||The AS3-From name of a client. This macro will only be resolved when used in the SITE command within an action to verify that the AS3 names are properly configured on the VersaLex server.|
||For EBICS, this macro will resolve to the order type of the EBICS transaction.|
Formatting %date% and %time% Macros
%date% setting is
yyyyMMdd and the default
%time% setting is
To specify a different
%time% format, use a pattern string in the 'Macro Date Format' and 'Macro Time Format' setting (system, host, or action level). See Advanced System Options for information about the Advanced tab under Configure System Options for definitions of these properties. Formats may also be specified as part of the macro definition, e.g.,
In the pattern, all ASCII letters are reserved as pattern letters, which are defined as the following:
||month in year||September & 09|
||day in month||15|
||hour in am/pm (1~12)||12|
||hour in day (0~23)||0|
||minute in hour||30|
||second in minute||24|
||day in week||Wednesday|
||day in year||259|
||day of week in month||2 (2nd Wed in September)|
||week in year||35|
||week in month||2|
||hour in day (1~24)||24|
||hour in am/pm (0~11)||0|
||time zone||Central Standard Time|
||escape for text||delimiter|
Any characters in the pattern that are not in the ranges of ['a'..'z'] and ['A'..'Z'] will be treated as quoted text. For instance, characters like '.', '#' and '@' will appear in the resulting date or time text even if they are not embraced within single quotes.
Examples Using Pattern Strings:
|%date% Format Pattern||Result|
|%time% Format Pattern||Result|
Macro Variable Usage Examples
Destination File Examples:
|Action Command||Destination File Result|
Source File Examples:
|Action Command||Source File Result|
After successful execution of 'LCOPY test.edi test2.edi':
|Execute On Successful Copy System Command||System Command Result|
Default Host Directory Examples:
Assume the system-level inbox is 'myInbox\' and the custom directory variable, '%custom1%', is set to '\\filsvr01\serverInbox\'.
|Host Default Directory (Inbox) Setting||Resolved Location|