I’ve recently been helping some people set up the MQ Managed File Transfer (MFT) REST API for an existing topology, and I thought I’d write up what we did to help others who might be wondering how to do this.
The MFT topology
Before we get the REST API set up, let’s start by looking at the MFT topology we shall be using. It’s a fairly simple one, consisting of three different systems.
System 1:
This system contains a single MQ installation, which has two queue managers associated with it:
- COORD_QM, which is the coordination queue manager for the topology.
- CMD_QM. This is the topology’s command queue manager.
The MQ installation also includes the mqweb server, which is configured with a basic user registry.
System 2:
System 2 contains the MFT agent AGENT1, along with its agent queue manager (QM1).
System 3:
The last system also hosts an MFT agent, called AGENT2, and its agent queue manager, which is called QM2.
Sender and receiver channels have been defined between the four queue managers, to allow messages to flow between them.
Here is a simple diagram showing what this looks like:
Figure 1: The existing MFT topology
And here’s a screenshot from the MQ Explorer that shows the four queue managers in the topology, and the status of AGENT1 and AGENT2:
Figure 2: The MQ Explorer shows that both agents in the topology are ready to do transfers.
Configuring the MFT REST API on System 1
The MFT REST API is not enabled in the mqweb server out of the box, so the first thing we need to do is turn it on. To do this, ensure the mqweb server is stopped by running the command:
endmqweb
and then run the command:
setmqweb properties -k mftRestMftEnabled -v true
Next, we need to configure the MFT REST to use the coordination queue manager COORD_QM and the command queue manager CMD_QM. This is done by running the following commands:
setmqweb properties -k mqRestMftCoordinationQmgr -v COORD_QM
setmqweb properties -k mqRestMftCommandQmgr -v CMD_QM
Now, there is one more step that we need to do. By default, the mqweb server only accepts requests that come from the system where it is running (which is System 1 in our topology). To allow users on Systems 2 and 3 to access the MFT REST API, run this command:
setmqweb properties -k httpHost -v "*"
To check that the configuration changes have been made correctly, we can run the command shown below:
dspmqweb properties
This should generate the following output:
name="httpHost" value="*"
name="mqRestMftCommandQmgr" value="CMD_QM"
name="mqRestMftCoordinationQmgr" value="COORD_QM"
name="mqRestMftEnabled" value="true"
Now we can start the mqweb server using the command:
strmqweb
To verify that the MFT REST API has started OK, open up the mqweb server’s messages.log file and check that it contains messages similar to the examples shown below:
[3/4/24 10:43:33:773 PST] 00000035 com.ibm.mq.mft.restapi.util.MessageConsumerRunnable I MQWB0417I: Subscription thread for topic 'SYSTEM.FTE/Transfers/#' successfully established a connection to the coordination queue manager.
[3/4/24 10:43:33:804 PST] 00000034 com.ibm.mq.mft.restapi.util.MessageConsumerRunnable I MQWB0417I: Subscription thread for topic 'SYSTEM.FTE/Log/#' successfully established a connection to the coordination queue manager.
Using the MFT REST API
Now that the MFT REST API is up and running, we can start using it.
The first thing to do is check the URI that it is listening on, by running the command:
dspmqweb
This generates the following output:
MQWB1124I: Server 'mqweb' is running.
URLS:
https://1.2.3.4:9443/ibmmq/rest/
https://1.2.3.4:9443/ibmmq/console/
Here we can see that that the REST API can be accessed on the URI https://1.2.3.4:9443/ibmmq/rest/, so let’s submit some requests to it to check that it works.
Getting agent status information
To start with, we will send a request to get the status of the agents in the topology. We can do this by running the following cURL command on System 2:
curl -k https://1.2.3.4:9443/ibmmq/rest/v2/admin/mft/agent/ -X GET -u mftadmin:mftadmin
The arguments here are:
-k https://1.2.3.4:9443/ibmmq/rest/v2/admin/mft/agent/
This is the URI that cURL will send the request to. Because it ends with /agent/, the REST API will return status information about all the agents in the topology.
-X GET
This parameter indicates that a GET request is being sent.
-u mftadmin:mftadmin
The -u parameter means that the GET request will be performed by the mqadmin user, which has a password of mqadmin.
When the command is run, it returns the following JSON payload:
{"agent": [
{
"name": "AGENT1",
"state": "ready",
"type": "standard"
},
{
"name": "AGENT2",
"state": "ready",
"type": "standard"
}
]}
The agent status information is stored on the coordination queue manager, so the fact that this command works indicates that the REST API can successfully access COORD_QM, which is great.
Now, lets submit a request to just get the status of AGENT1. We can do this by submitting the same cURL command as before but adding AGENT1 to the end of the URI, like this:
curl -k https://1.2.3.4:9443/ibmmq/rest/v2/admin/mft/agent/AGENT1 -X GET -u mftadmin:mftadmin
This time, the command returns the JSON shown below:
{"agent": [{
"name": "AGENT1",
"state": "ready",
"type": "standard"
}]}
Submitting a managed transfer request
We will now try submitting a managed transfer request to AGENT1. This will be sent to the command queue manager CMD_QM and then routed to the agent queue manager QM1 where it will be picked up and processed by the agent.
Our request will transfer the source file C:\MFTFiles\Input\File1.txt from System 2 to the file C:\MFTFiles\Output\File1.txt on System 3, so we need to create File1.txt on System 2.
The transfer request needs to be in a JSON format. Although it is possible to pass this directly into cURL on the command line, it is easier to store it in a file and pass that to cURL instead. To do this, we will create a file called C:\MFTFiles\Requests\request.json on System 2 containing the contents show below:
{
"sourceAgent": {
"qmgrName": "QM1",
"name": "AGENT1"
},
"destinationAgent": {
"qmgrName": "QM2",
"name": "AGENT2"
},
"transferSet": {
"item": [
{
"source": {
"name": "C:\\MFTFiles\\Input\\File1.txt",
"type": "file"
},
"destination": {
"name": " C:\\MFTFiles\\Output\\File1.txt ",
"type": "file"
}
}
]
}
}
We can then run a cURL command on System 2 to read the file and submit the transfer request to the REST API like this:
curl -k https://1.2.3.4:9443/ibmmq/rest/v2/admin/mft/transfer/ -i -X POST -d @C:\\MFTFiles\\Requests\\request.json -H "Content-Type: application/json" -H "ibm-mq-rest-csrf-token: \"\"" -u mftadmin:mftadmin
The arguments here are similar to the ones that we used for the cURL command to get the agent status information. The new ones are:
-I
This indicates that cURL should output any response headers returned by the REST API.
-d @C:\\MFTFiles\\Requests\\request.json
The -d parameter tells cURL to read the contents of the file C:\MFTFiles\Request\request.json and send it to the MFT REST API in the POST request.
-H "Content-Type: application/json"
-H "ibm-mq-rest-csrf-token: \"\""
These two parameters are needed to ensure that the required headers Content-Type and ibm-mq-rest-csfr headers are sent to the MFT REST API.
The Content-Type header will be set to application/json, indicating that the data in the POST request is in a JSON format.
The ibm-mq-rest-csrf-token header is set to the empty string.
When the command is run, it generates this output:
HTTP/1.1 202 Accepted
Location: https://1.2.3.4:9443/ibmmq/rest/v2/admin/mft/transfer/414d5120434d445f514d2020202020207f13e665013e0040
Date: Mon, 04 Mar 2024 18:52:44 GMT
Content-Language: en-US
Content-Length: 0
Notice that the response includes this URI:
https://1.2.3.4:9443/ibmmq/rest/v2/admin/mft/transfer/414d5120434d445f514d2020202020207f13e665013e0040
This shows that AGENT1 has picked up the transfer request and assigned it the transfer identifier 414d5120434d445f514d2020202020207f13e665013e0040.
We can use the URI to get the status of the transfer, by issuing the cURL command:
curl -k https://1.2.3.4:9443/ibmmq/rest/v2/admin/mft/transfer/414d5120434d445f514d2020202020207f13e665013e0040 -X GET -u mftadmin:mftadmin
which returns this:
{"transfer": [{
"id": "414D5120434D445F514D2020202020207F13E665013E0040",
"destinationAgent": {"name": "AGENT2"},
"originator": {
"host": "1.2.3.5",
"userId": "Administrator"
},
"sourceAgent": {"name": "AGENT1"},
"status": {"state": "successful"},
"statistics": {
"numberOfFileFailures": 0,
"numberOfFiles": 1,
"numberOfFileWarnings": 0,
"startTime": "2024-03-04T18:52:44.622Z",
"numberOfFileSuccesses": 1,
"endTime": "2024-03-04T18:52:45.052Z"
}
}]}
This shows that the transfer was successful, which is great! Just to prove it, here is a screenshot from the MQ Explorer that shows the transfer too:
Figure 3: The MQ Explorer shows the same status of the transfer as the REST API
There’s a lot more you can do with the MFT REST API, but hopefully this has given you enough information to get it running on your existing topology and start playing around with it. If you want to explore further, then the REST API Resources topic in the MQ documentation is a good place to start. This contains a list of the endpoints provided by the MFT REST API, along with details of how to use them.
As always, I hope this helps. If you have any questions, feel free to ask and I’ll be happy to answer them.