Configure the REST API for MFT

By default, the mqweb server which hosts the IBM MQ Console and REST API has the MFT REST API disabled. We can enable or disable the REST API for MFT, set the coordination queue manager, and specify the MFT reconnect timeout by using the setmqweb properties command.


Before you begin

You must be a privileged user to complete this procedure.

We can 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 or disabled. The mqRestMftCoordinationQmgr field shows the name of the coordination queue manager, and the mqRestMftReconnectTimeoutInMinutes field shows the timeout value for MFT requests. For more information, see dspmqweb.

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.sh. For example:
export WLP_USER_DIR=/var/mqm/web/installation1

For more information, see Create the Liberty server definition.


About this task

When you configure the REST API for MFT, we can configure three properties:

  • Whether the REST API for MFT is enabled. By default, it is disabled.
  • The name of the coordination queue manager from which information is retrieved when we use the MFT REST API resources. This queue manager must be a queue manager on the same machine as the mqweb server. The REST API for MFT establishes a bindings connection to this queue manager when the mqweb server starts.

    By default, this queue manager name is blank. If a value is not set, and the MFT REST API is invoked, an HTTP 400 is returned.

  • The timeout, in minutes, after which the REST API for MFT stops trying to connect to the coordination queue manager. 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.

    After the reconnection times out, the next attempt to reconnect is made when either the /transfer or the /agent REST API resources are invoked. If this reconnection attempt fails, MFT will again attempt to reconnect every five minutes until the reconnect timeout has passed.

    By default, the timeout value is 30 minutes. If the MFT REST API is invoked when the coordination queue manager is not started, an HTTP 503 is returned.


Procedure

  1. Adjust the configuration of the REST API for MFT:

    • Configure whether the REST API for MFT is enabled by using the following command:

      setmqweb properties -k mqRestMftEnabled -v enabled

      where enabled is the value true if you want the REST API for MFT enabled, or false otherwise.

    • Configure the coordination queue manager from which transfer details are retrieved 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.

    • Configure the timeout, in minutes, after which the REST API for MFT stops trying to connect to the coordination queue manager by using the following command:

      setmqweb properties -k mqRestMftReconnectTimeoutInMinutes -v time

      where time specifies the time, in minutes, before the timeout occurs.

      • A value between 0-5 specifies that 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.
      • A value of -1 specifies that the REST API for MFT attempts to reconnect until the connection is successful.
  2. Restart the mqweb server by entering the following commands: 
    endmqweb
strmqweb