Important

   

This space contains documentation for TrueSight Server Automation 8.9.03 and the later service packs for 8.9. For earlier releases, see BMC Server Automation 8.9.

Examples of REST APIs

This topic provides an example for using REST APIs for patching the Microsoft Windows 2012 operating system. You can use a similar sequence for other supported operating systems.

Example 1: The following example describes how to use the REST APIs to deploy security patches on servers running Windows 2012 operating systems. The servers are listed in Windows 2012 smart groups. The analysis and remediation job must be executed with the execute_now option. Also, the job status must be notified through an email message.

Prerequisites:

  • Windows 2012 catalogs must be created.
  • Server Smart group for Windows 2012 operating system must be created.
  • Email notification must be configured on TrueSight Server Automation.

Steps:

  1. Create a session by using the POST: api/v1/sessions API.

     Click here to view the request and response.

    Request:

    {
      "user_name": "BLAdminUser",
      "password": "BLAdminPassword",
      "role_name": "BLAdminRole",
      "authentication_type": "SRP"
    }

    Request URL: https://<hostname>:<port>/rest/api/v1/sessions

    Response:

    {
      "session_id": "f00f29bd-0b6d-4080-9b7c-6ed74d05ed9f",
      "roles": [
        "BLAdmins"
      ],
      "expiration_time": "2019-06-14T20:01:14.899+0000",
      "default_role": "BLAdmins",
      "service_ticket": "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
    Wu3HhQ2FlfjOV3+sniPCzqhwIekKpOgBALRvejE= eNpz8nFMyc3MKwYAC+QC6w==",
      "_links": {
        "self": {
          "href": "https://<hostname>:<port>/rest/api/v1/sessions"
        }
      }
    }
  2. Authorize the session by using the Authorize button.

     Click here to view steps to authorize the session.

    1. In the top-right corner, click Authorize link .
    2. In the api-key (apiKey) field, enter the session ID generated by using the POST method.
    3. Click Authorize.
    4. (Optional) In the api-role  (apiKey) field, enter the user role and click Authorize. By default, the value of the default_role attribute of POST: /api/v1/sessions API response is used.
    5. Click Close.

  3. Get the list of catalogs for the Windows operating system by using the GET: api/v1/catalogs API.

     Click here to view the request and response.

    Request URL: https://<hostname>:<port>/rest/api/v1/catalogs?type=windows 

    Response:

    {
      "catalogs": [
        {
          "name": "Windows Patch Catalog",
          "description": "This is an example Patching Catalog for Windows Patching.",
          "type": {
            "id": 5022,
            "name": "Windows Catalog"
          },
          "group": {
            "id": 2000183,
            "name": "Patch Catalogs",
            "path": "/Workspace/Patch Catalogs"
          },
          "id": 2000208,
          "acl_id": 2000065
        },
        {
          "name": "API_WinZip_Catalog",
          "description": "",
          "type": {
            "id": 5022,
            "name": "Windows Catalog"
          },
          "group": {
            "id": 2000216,
            "name": "AutomationPatching",
            "path": "/AutomationPatching"
          },
          "status": {
            "progress_status": "complete",
            "is_usable": true,
            "result": {
              "status": "passed",
              "summary": [
                {
                  "object_type": {
                    "id": 114,
                    "name": "Hotfix Windows Installable"
                  },
                  "status": "ADDED",
                  "total_count": 60
                },
                {
                  "object_type": {
                    "id": 114,
                    "name": "Hotfix Windows Installable"
                  },
                  "status": "DOWNLOADED",
                  "total_count": 0
                },
                {
                  "object_type": {
                    "id": 114,
                    "name": "Hotfix Windows Installable"
                  },
                  "status": "UPDATED",
                  "total_count": 0
                },
                {
                  "object_type": {
                    "id": 114,
                    "name": "Hotfix Windows Installable"
                  },
                  "status": "OBSOLETED",
                  "total_count": 0
                },
                {
                  "object_type": {
                    "id": 114,
                    "name": "Hotfix Windows Installable"
                  },
                  "status": "FAILED",
                  "total_count": 0
                },
                {
                  "object_type": {
                    "id": 114,
                    "name": "Hotfix Windows Installable"
                  },
                  "status": "FAILED_TO_DOWNLOAD",
                  "total_count": 0
                },
                {
                  "object_type": {
                    "id": 114,
                    "name": "Hotfix Windows Installable"
                  },
                  "status": "INVALID_URL",
                  "total_count": 0
                },
                {
                  "object_type": {
                    "id": 308,
                    "name": "Windows Bulletin Installable"
                  },
                  "status": "ADDED",
                  "total_count": 23
                },
                {
                  "object_type": {
                    "id": 308,
                    "name": "Windows Bulletin Installable"
                  },
                  "status": "UPDATED",
                  "total_count": 0
                },
                {
                  "object_type": {
                    "id": 308,
                    "name": "Windows Bulletin Installable"
                  },
                  "status": "OBSOLETED",
                  "total_count": 0
                },
                {
                  "object_type": {
                    "id": 308,
                    "name": "Windows Bulletin Installable"
                  },
                  "status": "FAILED",
                  "total_count": 0
                }
              ]
            },
            "job_run_id": 16
          },
          "id": 2000221,
          "acl_id": 2000070
        },
        {
          "name": "API_Win2k12_Catalog",
          "description": "",
          "type": {
            "id": 5022,
            "name": "Windows Catalog"
          },
          "group": {
            "id": 2000216,
            "name": "AutomationPatching",
            "path": "/AutomationPatching"
          },
          "status": {
            "progress_status": "complete",
            "is_usable": true,
            "result": {
              "status": "passed",
              "summary": [
                {
                  "object_type": {
                    "id": 114,
                    "name": "Hotfix Windows Installable"
                  },
                  "status": "ADDED",
                  "total_count": 12518
                },
                {
                  "object_type": {
                    "id": 114,
                    "name": "Hotfix Windows Installable"
                  },
                  "status": "DOWNLOADED",
                  "total_count": 0
                },
                {
                  "object_type": {
                    "id": 114,
                    "name": "Hotfix Windows Installable"
                  },
                  "status": "UPDATED",
                  "total_count": 0
                },
                {
                  "object_type": {
                    "id": 114,
                    "name": "Hotfix Windows Installable"
                  },
                  "status": "OBSOLETED",
                  "total_count": 0
                },
                {
                  "object_type": {
                    "id": 114,
                    "name": "Hotfix Windows Installable"
                  },
                  "status": "FAILED",
                  "total_count": 0
                },
                {
                  "object_type": {
                    "id": 114,
                    "name": "Hotfix Windows Installable"
                  },
                  "status": "FAILED_TO_DOWNLOAD",
                  "total_count": 0
                },
                {
                  "object_type": {
                    "id": 114,
                    "name": "Hotfix Windows Installable"
                  },
                  "status": "INVALID_URL",
                  "total_count": 0
                },
                {
                  "object_type": {
                    "id": 308,
                    "name": "Windows Bulletin Installable"
                  },
                  "status": "ADDED",
                  "total_count": 976
                },
                {
                  "object_type": {
                    "id": 308,
                    "name": "Windows Bulletin Installable"
                  },
                  "status": "UPDATED",
                  "total_count": 0
                },
                {
                  "object_type": {
                    "id": 308,
                    "name": "Windows Bulletin Installable"
                  },
                  "status": "OBSOLETED",
                  "total_count": 0
                },
                {
                  "object_type": {
                    "id": 308,
                    "name": "Windows Bulletin Installable"
                  },
                  "status": "FAILED",
                  "total_count": 0
                }
              ]
            },
            "job_run_id": 18
          },
          "id": 2000225,
          "acl_id": 2000070
        }
      ],
      "total_records": 3
    }
  4. Note down the Catalog ID for Windows 2012 catalog from the response that you received in the previous step.

  5. (Optional) Update the catalog by using the PATCH: api/v1/catalogs/{id} API.

     Click here to view the request and response.

    Request URL:

    https://<hostname>:<port>/rest/api/v1/catalogs/2000225

     Response:

    {
      "schedule_id": 10
    }
  6. Create a patching job for the specific Catalog ID by using the POST/api/v1/patching-jobs API. Do the following:

    • In the group section, set security_patches to True.
    • Remove the list section.
    • In the target section, add Smart group servers. 
    • Remove the servers section.
    • Add notification details in the notification section for both analysis and remediation.
    • Set the execute_now parameter to True for both analysis and remediation. Alternatively, to set the execute_now parameter, you can also use the PATCH method (PATCH : /api/v1/patching-jobs/{id}).
     Click here to view the request and response.

    Request:

    {
    	"name": "patch_job",
    	"description": "Windows Analysis Job",
    	"group": {
    		"id": 2000229
    	},
    	"catalog": {
    		"id": 2000225
    	},
    	"max_parallel_targets": 0,
    	"execution_override": false,
    	"analysis": {
    		"windows": {
    			"group": {
    				"security_patches": true,
    				"security_tools": false,
    				"non_security_patches": false,
    				"exclude_service_packs": false
    			}
    		}
    	},
    	"remediation": {
    		"artifact_prefix": "WindowsPatchingJob",
    		"depot_group": {
    			"id": 2000004
    		},
    		"job_group": {
    			"id": 2000229
    		},
    		"remediation_options": {
    			"options": {
    				"schedule_options": {
    					"simulate": true,
    					"commit": true,
    					"staging": "direct",
    					"execute_job_now": true
    				}
    			}
    		}
    	},
    	"targets": {
    		"server_groups": [{
    				"id": 2000230
    			},
    			{
    				"path": "/ApiSmartGroupAutomation"
    			}
    		]
    	},
    	"notifications": {
    		"email": {
    			"value": "username@xyz.com",
    			"success": true,
    			"failure": true,
    			"aborted": true
    		},
    		"notification_url": {
    			"url": "http://dummynotificationurl.xyz.com:500/",
    			"accept": "json",
    			"retry_count": 10,
    			"retry_pause": 20,
    			"retry_timeout": 300
    		}
    	},
    	"execute_now": true
    }

    Response:

    {
      "id": {
        "job_id": 110,
        "job_version": 1
      },
      "name": "patch_job",
      "description": "Windows Analysis Job",
      "group": {
        "id": 2000229,
        "name": "PAJ_Windows",
        "path": "/PAJ_Windows"
      },
      "catalog": {
        "id": 2000225,
        "name": "API_Win2k12_Catalog",
        "path": "/AutomationPatching/API_Win2k12_Catalog"
      },
      "max_parallel_targets": 0,
      "execution_override": false,
      "analysis": {
        "windows": {
          "group": {
            "security_patches": true,
            "security_tools": false,
            "non_security_patches": false,
            "exclude_service_packs": false
          }
        }
      },
      "remediation": {
        "artifact_prefix": "WindowsPatchingJob",
        "depot_group": {
          "id": 2000004,
          "name": "BMC Maintenance",
          "path": "/BMC Maintenance"
        },
        "job_group": {
          "id": 2000229,
          "name": "PAJ_Windows",
          "path": "/PAJ_Windows"
        },
        "acl_policy_id": 0,
        "remediation_options": {
          "options": {
            "job_options": {
              "logging_level": "error_warnings",
              "flow_control": "by_server",
              "all_host_commit": false,
              "reset_job_on_failure": false,
              "single_job_mode": true,
              "agent_connection_timeout": 0,
              "reboot_options": "ignore_item_defined",
              "single_user_mode": "use_item_defined"
            },
            "phase_options": {
              "disk_space_check": "stage",
              "auto_rollback": true,
              "allow_rollback": true,
              "preserve_staging_on_failure": false,
              "overwrite_read_only_files": false,
              "ignore_copy_on_boot": true,
              "copy_locked_files": false,
              "com": {
                "register": "both",
                "unregister": "both"
              }
            },
            "schedule_options": {
              "simulate": true,
              "commit": true,
              "staging": "direct",
              "execute_job_now": true,
              "schedule_details": {}
            },
            "maintenance_window_options": {
              "pause": false,
              "pause_before": 0
            }
          }
        }
      },
      "targets": {
        "server_groups": [
          {
            "id": 2000230,
            "name": "ApiPatchingServerGroup",
            "path": "/ApiPatchingServerGroup"
          },
          {
            "id": 2000231,
            "path": "/ApiSmartGroupAutomation",
            "name": "ApiSmartGroupAutomation"
          }
        ]
      },
      "notifications": {
        "email": {
          "id": 2,
          "value": "username@xyz.com",
          "success": true,
          "failure": true,
          "aborted": true,
          "append_patch_analysis_result": false,
          "size_limit": -1,
          "list_failed_servers": false
        }
      },
      "schedules": [],
      "execute_now_schedule_id": 9,
      "acl": {
        "acl_id": 2000068,
        "aces": [
          {
            "role_id": 1000010,
            "role_name": "BLAdmins",
            "authorization_id": 10000,
            "authorization_name": "PatchingJob.*"
          }
        ],
        "acl_policies": []
      }
    }
  7. To monitor the status of the job, note down the job_id from the response that you received in the previous step. 

  8. Get the latest job_run_id of the specific job by using the GET : api/v1/patching-jobs/{id}/jobruns API.

     Click here to view the request and response.

    Request URL: https://<hostname>:<port>/rest/api/v1/patching-jobs/1003/jobruns

    Response:

    {
      "job_runs": [
        {
          "object_type": {
            "id": 7010,
            "name": "Windows Patching Job Run"
          },
          "job_run": {
            "job_run_id": 113
          },
          "job": {
            "job_id": 1003,
            "job_version": 1
          },
          "schedule_id": 157,
          "role_executed": {
            "id": 1000010,
            "name": "BLAdmins"
          },
          "user_executed": {
            "id": 1000010,
            "name": "BLAdmin"
          },
          "start_time": "2019-06-17 15:38:51.643",
          "end_time": "2019-06-17 15:40:49.37",
          "has_errors": true,
          "has_warnings": true,
          "is_cancelled": false,
          "is_reset": false,
          "progress_status": "complete",
          "is_reboot": false
        }
      ],
      "total_records": 1
    }
  9. Verify the following fields in the response of the previous step:
    • progress_status - This field displays the status.
    • has_errors - This field displays whether the execution was successful.
  10. Monitor the job results by using the GET : api/v1/patching-jobs/{id}/jobruns/{run_id}/results API.

     Click here to view the request and response.

    Request URL: https://<hostname>:<port>/rest/api/v1/patching-jobs/1003/jobruns/113/results

    Response:

    {
      "id": 113,
      "analysis": {
        "id": 114,
        "patches": {
          "type": {
            "id": 114,
            "name": "Hotfix Windows Installable"
          },
          "missing": 1,
          "installed": 0
        },
        "containers": {
          "type": {
            "id": 308,
            "name": "Windows Bulletin Installable"
          },
          "missing": 0,
          "installed": 0
        },
        "scanned_machines": 1,
        "not_scanned_machines": 0
      },
      "remediation": [
        {
          "id": 115,
          "download": {},
          "deploy": {
            "all": 1,
            "failed": 1,
            "not_started": 0,
            "paused": 0,
            "pending_reboot": 0,
            "pending_targets": 0,
            "running_targets": 0,
            "successful_targets": 0,
            "success_with_warnings": 0
          }
        }
      ]
    }
  11. If required, restart the target servers.
  12. Validate the deployment by running the analysis job by using the PATCH: api/v1/patching-jobs/{id} API.

     Click here to view the request and response.

    Request URL: https://<hostname>:<port>/rest/api/v1/patching-jobs/1003

    Response:

    {

      "schedule_id": 158

    }

Was this page helpful? Yes No Submitting... Thank you

Comments