IBM Performance Management

Using the API for Threshold Management Service

Use the Threshold Management Service API to complete Threshold Manager tasks from the command line. You can create scripts for automating such tasks as defining thresholds and assigning to resource groups.

About this task

This task has you use the OpenID Connect (OIDC) protocol to get an access token from the OIDC server on the Performance Management server. The access token gives you authorized access to the API for running operations until the token expires after 30 minutes.

Disabling OIDC authentication, which is required before you can enable single sign-on (SSO) between Performance Management and other IBM products that require LTPA for SSO, does not affect the API. The RESTful API continues to rely on OIDC and does not interfere with SSO. (See Disabling OpenID Connect authentication for the Performance Management console.)

The functions are described in the API Explorer, and available while you are logged into the Threshold Management Service API:
  • Get all thresholds or get a specific threshold. You can filter the request with these attributes: label, which corresponds to the threshold name; _appliesToAgentType, which corresponds to the 2-character product code, and _uiThresholdType, which corresponds to the threshold type that is shown in the Threshold Manager and Resource Group Manager pages of the Performance Management console. You can use _offset or _limit when getting thresholds
  • Post a single threshold or, with X-HTTP-Method-Override set to PATCH, update the definition of an existing threshold
  • Delete the specified threshold
  • Get all resource assignments or a specific resource assignment, which shows the thresholds that are assigned to each resource group. You can filter the request with these attributes: resource._id and threshold._id; and use these supported operators are = (equal) and != (not equal)
  • Post resource assignment, which assigns a single threshold to a single resource group
  • Delete a resource assignment, which removes a single threshold from a single resource group

Procedure

  1. On the system where the Performance Management server is installed, open the following file and copy the client ID and client secret: 
    /opt/ibm/wlp/usr/shared/config/clientSecrets.xml
    The following example shows what the file contains: 
    <server>
  <variable name="client.secret.apmui" value="{xor}J2oZKWQsHXVxeCJwBGscfQ40d2N+cBUPZmltKRNz" />
  <variable name="client.id.apmui" value="rpapmui" />
</server>
  2. Use an XOR decoder to get the actual password value. Example: x5Fv;sB*.'}/[4C"Qk(<!/JP962vL
  3. To get an access token, contact the token endpoint of the OIDC server with the four required items: username, password, client_id, and client_secret. In this curl example, the client_secret has the value secret: 
    curl --tlsv1.2 -v -k -d grant_type=password&client_id=rpapmui&client_secret=secret&username=apmadmin&password=apmpass&scope=openid https://example.mycompany.com:8099/oidc/endpoint/OP/token
    Output:
    {"access_token":"jnz4Ad0zpeCpYcUlUf7o4A40tz5trnIW9GutICG8","token_type":"Bearer","expires_in":1800,"scope":"openid","refresh_token":"VsCWUhPHBRpidD2F1PVyZ2LNGMuQPTN837t3OoqZj71FcBfsGE"}
  4. Extract the access_token value. Looking at the output in the previous example, the value is jnz4Ad0zpeCpYcUlUf7o4A40tz5trnIW9GutICG8.
  5. Enter requests to the Threshold Management Service API that include the access_token in the authorization header. Access is authorized until the token expires, 1800 seconds after issuance. This example is a GET request for thresholds that specifies the header (curl option -H) from the previous example: 
    curl --tlsv1.2 -v -k -H "Authorization: Bearer jnz4Ad0zpeCpYcUlUf7o4A40tz5trnIW9GutICG8" https://example.mycompany.com:8091/1.0/thresholdmgmt/threshold_types/itm_private_situation/thresholds
    The changes you make to thresholds in the API are effective immediately and displayed in the Threshold Manager.
  6. For any thresholds that you want to assign to a resource group, take these steps to learn the resource group ID:
    1. Create a threshold in the Performance Management console and assign it to a resource group. For instructions, see Threshold Manager.
    2. Run the GET operation to learn the threshold ID: 
      GET /threshold_types/itm_private_situation/thresholds?_filter=label%3DMy_threshold
      where My_threshold is the name of the threshold that you created in the previous step.
    3. Make the following request to learn the resource group ID that the threshold is assigned to: 
      GET /resource_assignments?_filter=threshold._id=###
      where IP_address is the IP address of the Performance Management server and ### is the threshold ID number that you obtained in the previous step. Sample output:
      {
"threshold": {
"_id": "1010"
},
"resource":{
"_id": "41FissU-jCKCtTZPw_mTTA"
}
}
    The resource group ID is shown in the output, and you can use it for assigning thresholds to.
  7. Open the API Explorer in your browser: https://developer.ibm.com/api
  8. In the My APIs search box, enter performance management and click Search icon.
  9. Select the IBM Performance Management: Threshold Management Service API.

Example

This command returns all the thresholds that are registered with the server:
GET /threshold_types/itm_private_situation/thresholds
This command returns the information for the threshold with the label (name) My_threshold.
GET /threshold_types/itm_private_situation/thresholds?_filter=label%3DMy_threshold
This command returns all the thresholds for agent type LZ, which is the component code for the Linux OS agent.
GET /threshold_types/itm_private_situation/thresholds?_filter=_appliesToAgentType%3DLZ
This command has the same output as the previous command but the agent name as it appears in the Performance Management console is given.
GET /threshold_types/itm_private_situation/thresholds?_filter=_uiThresholdType%3DLinux OS
This command returns all the resource groups that threshold 123 is assigned to:
GET /resource_assignments?_filter=threshold._id=123