This documentation applies to the 8.0 version of Remedy Action Request System, which is in "End of Version Support." You will not be able to leave comments.

To view the latest version, select the version from the Product version menu.

Enabling the runmacro command-line utility

The AR System server includes the runmacro utility, which can run a macro or export data as a background process without a GUI. The runmacro utility can be run from filter or escalation workflow or as a standalone process (that is, a Windows batch file or a UNIX script). Third-party applications can use the runmacro utility to run AR System macros. Because runmacro functionality provides no GUI support, it can execute processes that run in the background, but it cannot perform tasks such as displaying a results list.

To run the runmacro utility, you must set the library path to the directory where the runmacro executable resides. To do so, use these commands:

  • Solaris and Linux

  • HP-UX

  • AIX


The runmacro command has the following formats. Items between square brackets are optional. Enclose arguments that contain blank spaces or symbols in double quotation marks.

  • You can use the original version of runmacro without the output file option (-o):

runmacro [-h <homeDir>] [-d <macroDir>]
[{-x <serverName>} ...] { -e | -i } <macroName>
[-p <parameter>=<value> ...] \[\-U  <userName>] [-P <password>]
[-Q <internalQualificationFormat>]
[-q <clientToolQualificationFormat>]
[-Z <internalFormatQualificationFileName>]
[-z <clientToolFormatQualificationFileName>]
[{-w | -W } <externalAuthenticationString>] [-a <portNumber>]
  • You can use runmacro with the -o option to use the arcopy syntax, which copies the output to a file:

runmacro -o <outputFileName> [{-x <server>} ...] -U  <user>]
[-P <password>] [{ -f | -s} <form>] [-t {arx|csv|xml}]
[-Q <internalQualificationFormat>]
[-q <clientToolQualificationFormat>]
[-Z <internalFormatQualificationFileName>]
[-z <clientToolFormatQualificationFileName>]
[{-w | -W } <externalAuthenticationString>] [-a <portNumber>]

When you use the -o option to export data with attachments, the attachments folder is created in the same directory as the export file. The attachments folder name uses an integer time stamp (for example, 917732184), and the folder location is specified in the output file name of the runmacro command.

When creating macros, you can record a login with the proper permissions if you perform actions that require those permissions (for example, an administrator deleting records). If your macro does not record a login, you must specify login information using the -U option and the -P option (if necessary).

This table lists the runmacro options, which can appear in any order in the command line:




Output file name — Name of the file in which to store the data. The file is initially truncated, and then all the data is written to the file (one data set after another).


Home directory — Path to the ARSystemHomeDir directory. If you do not specify the -d option, runmacro also looks in this directory for the arcmds directory that contains the macro to run.


Macro directory — Directory that contains the macro if your macro is not in the ARSystemHomeDir\arcmds directory or if you do not have an ARSystemHomeDir directory.


Server name — Name of a server to connect to. This option might be included more than once to connect to multiple servers. Use the following format: -x serverName

-e (or -i )

Macro name — Specifies the macro to run.


Parameter — Value for a parameter. There might be more than one -p option in a command line. If the macro specified (using the -e or -i options) has a parameter, a value can be supplied by naming that parameter and assigning a value. If the parameter name or value includes a space or other special character, the data must be enclosed in quotation marks to cause proper interpretation of the special characters. Use the following format for each parameter specified: -p parameter = value


User name — Required login parameter that identifies the user account. The -U option must be in uppercase.


Password — Optional login parameter that identifies the user account. Omit the -P if the user account has no password. The -P option must be in uppercase.


Internal qualification format — Query in AR System internal format.


Client tool qualification format — this is a regular query.

Within the query string, double quotation marks must be preceded by a backslash (), which functions as an escape character. For example:

runmacro.exe -o <outputFileName>-x <serverName>
-U <userName> -P <password> -f <form> -t {arx|csv|xml}
-q "'Submitter'=\"tester\" AND ('Create Date' >|
\"5/9/2007\" AND 'Create Date' < \"5/16/2007\")"


Internal format qualification file name — File name containing the query in Remedy internal format.


Client tool format qualification file name — File name containing a regular query.

-w (or -W)

Authenticator — Name of the external authentication string or Windows NT domain. This is related to the Login window's Authentication field. See Authentication String Alias introduction.


Port number — Port number to which to connect the server.

-f (or -s)

Form name — Form that is exported. The -f (or -s) option can be repeated multiple times if there are several forms to export. If multiple servers are selected, each server is searched for the form, and the first one found is all that is exported. To control this, specify only one server environment for the operation. If the -f (or -s) option is not specified, the system exports all available regular data forms. It does not export join or external forms.


Type of file to write — File type for the output file: arx, csv, or xml. If not specified, the default of arx is used.


Forces override — If the user has already logged in as this same user from a different IP address, this option tells the server to use the new IP address of the runmacro client and invalidates the old IP address.

Note: This option does not apply to users with administrator permissions.

This version of the documentation is no longer supported. However, the documentation is available for your convenience. You will not be able to leave comments.