Configuring the REST API for MFT

[Long Term Support] By default, the mqweb server which hosts the IBM® MQ Console and REST Services does not have MFT enabled. You can configure whether the REST API for MFT is enabled, set the coordination queue manager, and specify the MFT reconnect timeout by using the setmqweb properties command. [V9.1.2 Mar 2019] For a create REST API command like Create transfer you must add mqRestMftCommandQmgr. [Continuous Delivery] [V9.1.4 Dec 2019] By default, the mqweb server which hosts the IBM MQ Console and REST Services does not have MFT enabled.

Before you begin

You need:

To exercise MFT REST services, you need to enable the MFT REST service by setting mqRestMftEnabled to true and also set the command queue manager name to mqRestMftCoordinationQmgr:
```
setmqweb properties -k mqRestMftEnabled -v true 
setmqweb properties -k mqRestMftCoordinationQmgr -v <coordinationQmgrName>
```
To submit any, create request, for example, create transfer or resource monitor, you need to set the mqRestMftCommandQmgr
```
setmqweb properties -k mqRestMftCommandQmgr -v <commandQmgrName>
```
Restart the mqweb server to enforce the values you have just set by issuing the endmqweb command followed by the strmqweb command.
Check the status of the web server by issuing the dspmqweb command.

To complete this task, you must be a user with certain privileges so that you can use the dspmqweb and setmqweb commands:

On z/OS®, you must have authority to run the dspmqweb and setmqweb commands, and write access to the mqwebuser.xml file.
On all other operating systems, you must be a privileged user.

To use the REST API for MFT, the caller must be authenticated to the mqweb server and must be a member of one or more of the MFTWebAdmin, or MFTWebAdminRO roles.

Attention:

Before issuing either the setmqweb or dspmqweb commands on z/OS, you must set the WLP_USER_DIR environment variable, so that the variable points to your mqweb server configuration.

To do this, issue the following command:

export WLP_USER_DIR=WLP_user_directory

where WLP_user_directory is the name of the directory that is passed to crtmqweb. For example:

export WLP_USER_DIR=/var/mqm/web/installation1

For more information, see Create the mqweb server.

About this task

When you configure the REST API for MFT timeout, note that the first attempt to re-establish the connection is made immediately after the connection to the coordination queue manager is broken. If this fails, there is an interval of five minutes between every reconnection attempt. Therefore, setting a value between 0-5 results in only one attempt to reconnect.

After the reconnection times out, the next attempt to reconnect is made when any of the REST API for MFT resources are invoked. If this reconnection attempt fails, MFT again attempts to reconnect every five minutes until the reconnect timeout has passed.

Procedure

View the current configuration of the REST API for MFT by using the following command:
dspmqweb properties -a
The mqRestMftEnabled field shows whether the REST API for MFT is enabled. The value is True if the messaging REST API is enabled, or False otherwise.

The mqRestMftCoordinationQmgr field shows the name of the coordination queue manager.

The mqRestMftCommandQmgr field shows the name of the command queue manager.

The mqRestMftReconnectTimeoutInMinutes field shows the reconnection timeout value, until the MFT Transfer Rest services stops attempting to connect to the coordination queue manager. For more information, see dspmqweb.
Configure whether the REST API for MFT is enabled:
1. Configure whether the REST API for MFT is enabled by entering the following command:
  
  setmqweb properties -k mqRestMftEnabled -v value
  
  where value is true if you want the REST API for MFT enabled, or false otherwise.
2. Restart the mqweb server by entering the following commands:
```
endmqweb
strmqweb
```
Configure the coordination queue manager from which transfer details are retrieved:
1. Configure the coordination queue manager by using the following command:
  
  setmqweb properties -k mqRestMftCoordinationQmgr -v qmgrName
  
  where qmgrName is the name of the coordination queue manager. The coordination queue manager must be on the machine where the mqweb server is running. By default, this queue manager name is blank. If a value is not set, the REST API for MFT does not work.
2. Restart the mqweb server by entering the following commands:
```
endmqweb
strmqweb
```
Configure the timeout, in minutes, after which the REST API for MFT stops trying to connect to the coordination queue manager:
1. Configure the timeout by using one of the following commands:
  - Set the timeout:
    setmqweb properties -k mqRestMftReconnectTimeoutInMinutes -v time
    
    where time specifies the time, in minutes, before the timeout occurs.
    
    If this value is set between 0-5, the REST API for MFT tries to reconnect to the coordination queue manager only once. If the connection fails, there are no attempts to re-establish the connection until the REST API is invoked.
    
    If this value is set to -1, the REST API for MFT attempts to reconnect until the connection is successful.
  - Reset the timeout to the default value of 30 minutes:
    setmqweb properties -k mqRestMftReconnectTimeoutInMinutes -d
2. Restart the mqweb server by entering the following commands:
```
endmqweb
strmqweb
```
Configure the command queue manager for a create request:
1. Configure the command queue manager by using the following command:
  
  setmqweb properties -k mqRestMftCommandQmgr -v qmgrName
  
  where qmgrName is the name of the command queue manager. The command queue manager must be on the machine where the mqweb server is running. By default, this queue manager name is blank. If a value is not set, the MFT REST API for a create command does not work.
2. Restart the mqweb server by entering the following commands:
```
endmqweb
strmqweb
```