run
The run command executes a MapForce Server execution file (.mfx file) supplied as argument. The MapForce Server execution file is created with MapForce; it essentially represents a mapping compiled for server execution.
Any input files required by the mapping are expected to be at the path specified at mapping design time in MapForce. If MapForce Server does not run on the same operating system as MapForce, the input files required by the mapping must be copied to the target machine alongside with the .mfx file, and must be referenced using a relative path. For information about configuring a mapping with respect to relative or absolute paths, refer to MapForce documentation (https://www.altova.com/documentation#mapforce). Other prerequisites may apply, depending on how you designed the mapping, see Preparing Mappings for Server Execution.
If the mapping returns a simple value such as string, this output is written in the stdout (standard output) stream. On the other hand, the success and error messages are available in the stderr (standard error) stream. If you do not want the standard output stream to be displayed on the screen together with the success or error messages, redirect either the standard output or the standard error stream (or both) to files. If neither the stdout nor the stderr streams are redirected, they are both displayed on the screen, combined.
For example, to redirect the standard output stream to a file, use:
mapforceserver run MyMapping.mfx > MyOutput.txt |
To redirect the standard error stream to a file, use:
mapforceserver run MyMapping.mfx 2> Diagnostics.log |
To redirect both streams simultaneously, use:
mapforceserver run MyMapping.mfx > MyOutput.txt 2> Diagnostics.log |
For further information about stream redirection, refer to the documentation of your operating system's command shell.
Syntax
Windows | MapForceServer run [options] MfxFile |
Linux | mapforceserver run [options] MfxFile |
Mac | mapforceserver run [options] MfxFile |
Command options
| --catalog | Specifies the absolute path to a root catalog file that is not the installed root catalog file. The default value is the absolute path to the installed root catalog file, see Catalog Files. Form: --catalog=FILE |
--cert | --certificatespath | This option is applicable to MapForce Server running on Linux. It specifies the path to the directory where any certificate files required by the mapping are stored. Form: --certificatespath=DIRECTORY
See also Digital Certificate Management. |
--cred | --credential=KEY:VALUE | Setting this option is meaningful if the mapping contains credentials that you have defined at mapping design time in MapForce. KEY is the credential name as it was defined in MapForce. VALUE consists of one or more name-value pairs, for example:
name1=value1&name2=value2
Where name is any of the following:
•username •password •oauth:token
When using multiple name-value pairs separated by ampersand, enclose the KEY:VALUE part within quotes. For examples, see Credentials. |
--gc | --globalresourceconfig | This option is applicable if the mapping consumes Global Resources. It specifies the name of the global resource configuration. This option must be used together with the --globalresourcefile option. |
--gr | --globalresourcefile | This option is applicable if the mapping consumes Global Resources. It specifies the path of the global resource definition file. This option must be used together with the --globalresourceconfig option. |
--l | --lang | The language used for displaying messages. |
--p | --param | This option is applicable if the mapping was designed to take input parameters. It assigns a value to a parameter defined in the mapping. Form: --param=ParamName:ParamValue. The --param switch must be used before each parameter. Use quotes if ParamName or ParamValue contains a space. For example: --p=company:"Nanonull Inc".
For more information about mappings that take input parameters, refer to MapForce documentation (https://www.altova.com/documentation#mapforce). |
| --taxonomy-package | Specifies the absolute path to an additional XBRL taxonomy package as described in the Taxonomy Packages 1.0 recommendation. The value of FILE gives the location of the taxonomy package. Add the option multiple times to specify more than one taxonomy package. Form: --taxonomy-package=FILE |
| --taxonomy-packages-config-file | Specifies the path to a configuration file called TaxonomyPackagesConfig.json, used to load XBRL taxonomy packages. This configuration file is updated every time when you add, remove, activate, or deactivate XBRL taxonomy packages from the graphical user interface of Altova XMLSpy, MapForce, or StyleVision. If you have added custom XBRL taxonomy packages using one of the products above, the file is located at C:\Users\<username>\Documents\Altova. Form: --taxonomy-packages-config-file=FILE |
Examples
This example shows you how to run a mapping execution file (.mfx) with MapForce Server on Windows. The mapping used in this example reads an input file, Employees.xml, and produces two output files (PersonList.xml and Contacts.xml).
First, let's generate the MapForce Server execution (.mfx) file, as follows:
1.Run MapForce and open the following MapForce design file (.mfd file): C:\Users\<user>\Documents\Altova\MapForce2024\MapForceExamples\ChainedPersonList.mfd.
2.On the File menu, click Compile to MapForce Server Execution File.
3.When prompted, save the .mfx file to C:\temp directory. This will be the working directory where the mapping will be executed by MapForce Server.
Next, let's open a command line prompt and change the working directory to C:\temp\.
cd C:\temp |
Finally, run the following command to execute ChainedPersonList.mfx. In this example, MapForce Server is called using an absolute path. (To call it with a relative path, add the executable's path to your system's PATH environment variable).
"C:\Program Files (x86)\Altova\MapForceServer2024\bin\MapForceServer.exe" run ChainedPersonList.mfx |
The two output files (PersonList.xml and Contacts.xml) are generated in the working directory. Importantly, this mapping is configured to use absolute paths, which is why the mapping ran successfully and did not require that the input Employees.xml file exists in the working directory. The Employees.xml file actually exists in the MapForce Examples folder mentioned above and is referenced through an absolute path. To specify whether paths should be treated as absolute or relative, right-click the mapping in MapForce, select Mapping Settings, and then select or clear the Make paths absolute in generated code check box. Whenever you change the mapping settings, make sure to re-compile the mapping to .mfx. For more information, see Preparing Mappings for Server Execution.