Altova MapForce 2023 Enterprise Edition

After you compile the mapping to a MapForce Server execution file (.mfx), MapForce Server will run the .mfx file depending on your choices at mapping design time, as explained in Creating Credentials.


If you selected the Include in MapForce Server Execution File and Mapping Deployment check box when creating the credential in MapForce, MapForce Server will use at mapping runtime any credentials that were stored in the .mfx file. This means that you can run the mapping with a command such as:


<exec> run mapping.mfx


Where <exec> is the path to the MapForce Server executable. This path can be either absolute or, if the current directory is the same as the executable, you can enter just the executable name.


If you entered only the credential name (without username and password) in MapForce, then you must explicitly provide these details at mapping runtime, with the help of the --credential command line option available for the run command. This way, you can use, for example, a different set of credentials in production, as opposed to those used when you designed the mapping. The --credential option has the form --credential=KEY:VALUE., where


KEY is the name of the credential as it was defined in MapForce.

VALUE is a credential property, or a list of properties separated by ampersand (&). For credentials of type "password", the possible properties are username and password. For credentials of type OAuth 2.0, the only supported property is oauth:token.

The actual property values are supplied just like query parameters in a URL, using the "=" sign.


For example:


<exec> run mapping.mfx --credential="mycredential:username=admin&password=4xJ38dnx7"


In the code listing above, the value of the --credential option was enclosed within quotes in order to treat the value literally, since the username and password are separated by an ampersand character.


If your mapping needs multiple sets of named credentials to run, you can specify the --credential option multiple times.


The credentials supplied as command line options take precedence over stored credentials.


If you did not select the Include in MapForce Server Execution File and Mapping Deployment check box, the sensitive fields are missing. This means that you must supply the password at the command line while still referring the credential by its name, for example:


<exec> run mapping.mfx --credential=mycredential:password=4xJ38dnx7


The following fields are considered sensitive data:


Password (for credentials of type "Password")

Client Secret, Access Token, and Refresh Token (for credentials of type "OAuth 2.0")


For mappings that require OAuth 2.0 authorization, the MapForce Server command line accepts an OAuth 2.0 access token as input at the mapping runtime. Note that the MapForce Server command line does not provide an interactive GUI by design, so you will need to obtain the OAuth 2.0 access token by external means (for example, by requesting it with MapForce) when using the command line specifically. This is, however, not necessary if MapForce Server runs under FlowForce Server management, since the latter is capable of acquiring a new OAuth 2.0 access token at runtime by itself.


At the command line, running the mapping with stored credentials is possible as long as the stored OAuth 2.0 token has not expired or has not been revoked by the Web service provider. To address this, supply a new OAuth 2.0 access token (obtained by some external means) by using the --credential option, for example:


<exec> run mapping.mfx --credential=my_oauth_credential:oauth:token=jdsaflkajlkewsaiurthczv904215-jhd




my_oauth_credential is the name of the OAuth 2.0 credential created from MapForce.

oauth:token is the way to indicate to MapForce Server that a new OAuth 2.0 access token is being supplied at runtime.


MapForce Server API

The MapForce Server API provides methods to create credentials, add properties to credentials, and close credentials after you finished declaring them. For more details, refer to the MapForce Server documentation (

© 2016-2022 Altova GmbH