IT27730: Behavioural differences between the MQ V9.1.0.1 MFT REST API on Distributed Platforms and z/OS

APAR status

• Closed as program error.

Error description

• There are some behavioural differences between the IBM MQ
  V9.1.0.1 Managed File Transfer (MFT) REST API on distributed
  platforms, and the MFT REST API shipped as part of IBM MQ
  Managed File Transfer for z/OS V9.1.0.1. The differences are
  shown below:
  
  Difference 1:
  --------------
  If the IBM MQ V9.1.0.1 MFT REST API, running on a distributed
  platform, connects to a coordination queue manager that does not
  have the SYSTEM.FTE topic defined, the following error is
  returned:
  {
   "error": [
    {
     "action": "Create the SYSTEM.FTE topic, set appropriate
  authorities, and resubmit the request.",
     "completionCode": 2085,
     "explanation": "The SYSTEM.FTE topic must be created and have
  appropriate authorities before using the MFT REST API.",
     "message": "MQWB0419E: An attempt to create a subscription to
  topic SYSTEM.FTE failed. The root MQ reason code was 2 :
  'MQRC_UNKNOWN_OBJECT_NAME'.",
     "msgId": "MQWB0419E",
     "reasonCode": 2,
     "type": "rest"
    }
   ]
  }
  This error contains incorrect values for the "completionCode"
  and "reasonCode" strings:
  
  - "completionCode" should be set to 2, rather than 2085.
  - "reasonCode" should be 2085, and not 2.
  
  This issue has been resolved in IBM MQ MFT for z/OS V9.1.0.1.
  
  Difference 2:
  --------------
  When using the IBM MQ MFT for z/OS V9.1.0.1 REST API to query
  information about a managed transfer, specifying a managed
  transfer identifier that does not exist, then the request fails
  with
  status code 404.
  
  However, if the IBM MQ V9.1.0.1 MFT REST API, running on a
  distributed platform, is used to query information about a
  managed transfer, passing in a managed transfer identifier that
  does not exist, then the request fails and incorrectly returns
  status code 400.
  
  Difference 3:
  --------------
  A user logs in to the IBM MQ MFT for z/OS V9.1.0.1 REST API,
  specifying a user identifier that has the following roles:
  - MFTWebAdmin.
  - MQWebUser.
  After logging in, the user issues a GET request on the URI
  /ibmmq/rest/v1/login. This returns the following information:
  {
   "user": [
    {
     "name": "USER1",
     "role": [
      "MFTWebAdmin"
      "MQWebUser"
     ]
    }
   ]
  }
  
  Another user logs into the IBM MQ V9.1.0.1 MFT REST API running
  on a distributed platform, specifying a user identifier that
  also has the:
  - MFTWebAdmin.
  - MQWebUser.
  roles. When the user issues an GET request on the URI
  /ibmmq/rest/v1/login, the following information is returned:
  {
   "user": [
    {
     "name": "USER1",
     "role": [
      "MQWebUser"
     ]
    }
   ]
  }
  This is missing the fact that the user has the "MFTWebAdmin"
  role.
  

Local fix

Problem summary

• ****************************************************************
  USERS AFFECTED:
  This issue affects users of the IBM MQ V9.1.0 Managed File
  Transfer (MFT) REST API on distributed platforms.
  
  
  Platforms affected:
  Windows, Solaris x86-64, Solaris SPARC, Linux on zSeries, Linux
  on x86-64, AIX, IBM iSeries, Linux on Power, Linux on S390
  
  ****************************************************************
  PROBLEM DESCRIPTION:
  Shortly after the release of IBM MQ V9.1.0.0, fixes for the
  following issues were delivered into the IBM MQ for z/OS V9.1
  codebase:
  
  ----------------------------------------------------------------
  ------
  Issue 1:
  --------
  If the IBM MQ MFT REST API connected to a coordination queue
  manager that did not have the SYSTEM.FTE topic defined, the
  following error was returned:
  {
   "error": [
    {
     "action": "Create the SYSTEM.FTE topic, set appropriate
  authorities, and resubmit the request.",
     "completionCode": 2085,
     "explanation": "The SYSTEM.FTE topic must be created and have
  appropriate authorities before using the MFT REST API.",
     "message": "MQWB0419E: An attempt to create a subscription to
  topic SYSTEM.FTE failed. The root MQ reason code was 2 :
  'MQRC_UNKNOWN_OBJECT_NAME'.",
     "msgId": "MQWB0419E",
     "reasonCode": 2,
     "type": "rest"
    }
   ]
  }
  
  This error contained incorrect values for the
  "completionCode"and "reasonCode" strings:
  - "completionCode" should have been set to 2, rather than 2085.
  - "reasonCode" should have 2085, and not 2.
  
  ----------------------------------------------------------------
  ------
  Issue 2:
  --------
  When using the IBM MQ MFT REST API to query information about a
  managed transfer, passing in a managed transfer identifier that
  does not exist, then the request failed and incorrectly returned
  status code 400. It should have returned status code 404.
  
  ----------------------------------------------------------------
  ------
  Issue 3:
  --------
  A user logged in to the IBM MQ MFT REST API, where the user had
  the following roles:
  - MFTWebAdmin.
  - MQWebUser.
  After logging in, the user issued a GET request on the URI:
  
  /ibmmq/rest/v1/login.
  
  This returned the following information:
  {
   "user": [
    {
     "name": "USER1",
     "role": [
      "MQWebUser"
     ]
    }
   ]
  }
  The response was missing the fact that the user has the
  "MFTWebAdmin" role.
  ----------------------------------------------------------------
  ------
  
  This meant that the fixes for the issues was included in IBM MQ
  V9.1.0.1 for z/OS.
  
  However, the fixes were not included in IBM MQ V9.1 codebase for
  distributed platforms. As a result, the three issues mentioned
  above still occurred when using the IBM MQ V9.1.0.1 MFT REST API
  on a distributed platform.
  

Problem conclusion

• The IBM MQ V9.1 MFT REST API on distributed platforms has been
  updated so that:
  
  ----------------------------------------------------------------
  ------
  - If the IBM MQ MFT REST API connects to a coordination queue
  manager that does not have the SYSTEM.FTE topic defined, the
  following error will be returned returned:
  {
   "error": [
    {
     "action": "Create the SYSTEM.FTE topic, set appropriate
  authorities, and resubmit the request.",
     "completionCode": 2,
     "explanation": "The SYSTEM.FTE topic must be created and have
  appropriate authorities before using the MFT REST API.",
     "message": "MQWB0419E: An attempt to create a subscription to
  topic SYSTEM.FTE failed. The root MQ reason code was 2 :
  'MQRC_UNKNOWN_OBJECT_NAME'.",
     "msgId": "MQWB0419E",
     "reasonCode": 2085,
     "type": "rest"
    }
   ]
  }
  
  ----------------------------------------------------------------
  ------
  - When the IBM MQ MFT REST API is used to query information
  about a managed transfer, passing in a managed transfer
  identifier that does not exist, then the request fails and
  returns status code 404.
  
  ----------------------------------------------------------------
  ------
  - If a user who has been assigned one of following roles:
  
      - MFTWebAdmin.
      - MFTWebAdminRO.
  
  logs into the IBM MQ MFT REST API, and then issues a GET request
  on the URI:
  
      /ibmmq/rest/v1/login.
  
  then the information returned will correctly show the roles
  assigned to the user.
  
  ----------------------------------------------------------------
  ------
  
  ---------------------------------------------------------------
  The fix is targeted for delivery in the following PTFs:
  
  Version    Maintenance Level
  v9.1 CD    9.1.3
  v9.1 LTS   9.1.0.2
  
  The latest available MQ maintenance can be obtained from
  'WebSphere MQ Recommended Fixes'
  http://www-1.ibm.com/support/docview.wss?rs=171&uid=swg27006037
  
  If the maintenance level is not yet available information on
  its planned availability can be found in 'WebSphere MQ
  Planned Maintenance Release Dates'
  http://www-1.ibm.com/support/docview.wss?rs=171&uid=swg27006309
  ---------------------------------------------------------------
  

Temporary fix

Comments

APAR Information

• APAR is sysrouted FROM one or more of the following:

• APAR is sysrouted TO one or more of the following:

Fix information

• Fixed component name

  IBM MQ MFT V9.1

• Fixed component ID

  5724H7272

Applicable component levels