IV89313: ITNCM REST/NSM API DOCUMENTATION CORRECTIONS.

APAR status

• Closed as documentation error.

Error description

• ITNCM Rest/NSM API documentation corrections.
  
  
  Please update the ITNCM Rest/NSM API documentation to reflect
  the correct behavior/examples:
  
  1)   ITNCM REST API JSON request format changed without notice
  or documentation change -
  
  Using ITNCM v6.4.2.1 on Linux I, I observed that the JSON
  parameters used in the request body of POST operation to
  execute a service template have changed without notice.
  Existing JSON strings that functioned correctly in all previous
  ITNCM versions now fail.  In particular, the parameter name for
  the service template ID has changed from "id" to
  "serviceTemplateId". Examples are provided later in this
  problem description.
  
  The business impact is that the client side of all REST API
  integrations / or customer-built utilities that worked with
  ITNCM prior
  to v6.4.2.x must now be changed to used the new parameter name
  if they use JSON as input.  The  format for XML request bodies
  does not appear to have changed, only the JSON format. This is
  further complicated since the documentation stills shows the
  old (no longer functional) version of the JSON format; see the
  example JSON text in the docs at section:
  http://www.ibm.com/support/knowledgecenter/SS7UH9_6.4.2/ncm/wip/
  api/reference/ncm_http_post_for_service_ref_id.html.
  
  Fortunately, in lieu of correct documentation, the new format
  of the JSON request body is correctly shown when retrieving an
  example request body for servicetemplate for a  device, using a
  URL such as:
  
  http://my-server:16310/nsm/servicetemplate/{template-di}/devicei
  d/1{device-id}
  
  JSON request body text examples:
  
  JSON request body for ITNCM v6.4.1.2:
  {
    "clientParameters": [
      {
        "name": "PARAM1",
        "value": "some text"
      },
      {
        "name": "PARAM2",
        "value": " more text"
      }
    ],
    "deviceID": 1428,
    "id": 1
  }
  
  The above example now fails with the error: Error 400:
  NSM-ERR-61 An id
  is required for a service template.
  
  The new required format (for ITNCM v 6.4.2.1) is:
  {
    "clientParameters": [
      {
        "name": "PARAM1",
        "value": "some text"
      },
      {
        "name": "PARAM2",
        "value": " more text"
      }
    ],
    "deviceID": 1428,
    "serviceTemplateId": 1
  }
  
  
  
  
  2)  ITNCM NSM does not return correct a service template
  example for DISCOVER opertations
  
  When using ITNCM v6.4.2.1 on Linux, using an NSM REST GET
  operation for a service template for discovering a device does
  not return a JSON or XML example in the correct format.
  
  The format for the JSON or XML REST request body to invoke a
  service for a DISCOVER operation is not documented in the ITNCM
  documentation, so the only way for a customer to know how to
  format such a request is to try to obtain one from a URL such
  as
  
  http://my-server:16310/nsm/servicetemplate/{template-id}/devicei
  d/{device-id}.
  
  However, when discovering a new device, there is no deviceId
  for that device in ITNCM yet. The other logical options are to
  try to fetch an example using URLS such as:
  
  http://my-server:16310/nsm/servicetemplate/{template-id}
  http://my-server:16310/nsm/servicetemplate/{template-id}/devicei
  d/myNewDeviceName
  http://my-server:16310/nsm/servicetemplate/{template-id}/devicei
  d/{device-id} where device-id is the ID of an existing device
  in ITNCM.
  
  The first two formats fail with errors, and do not return an
  example service template.  The last format returns an incorrect
  example, for instance:
  
  {
      "deviceID": 1428,
      "serviceTemplateId": 52
  }
  
  The correct format (based on experimentation and internal log
  review in previous ITNCM versions plus updates for the new
  serviceTemplateId param name) is:
  
  {
    "realm": "ITNCM/Test1",
    "deviceName": "PE1",
    "createRealm": "false",
    "serviceTemplateId": 603
   }
  

Local fix

Problem summary

• ****************************************************************
  * USERS AFFECTED:                                              *
  * Users using NSM API                                          *
  ****************************************************************
  * PROBLEM DESCRIPTION:                                         *
  * unclear documentation for NSM API usage                      *
  ****************************************************************
  * RECOMMENDATION:                                              *
  * it will be fixed in 6.4.2.3 release documentation            *
  ****************************************************************
  

Problem conclusion

• see recommendation section
  

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

Applicable component levels