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:

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"
   }
}
}
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.
2. Use one of the following authentication methods:
  
  Authorization (apiKey)
  In the Value field, enter the authorization header or the Remedy Single Sign-On token, and click Authorize. For information about obtaining the Remedy Single Sign-On token, see Implementing Remedy Single Sign-On authentication.
  api-key (apiKey)
  This authentication method is deprecated. BMC recommends using the authorization header.
  api-role (apiKey)
  In the Value 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.
3. Click Close.
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
}
Note down the Catalog ID for Windows 2012 catalog from the response that you received in the previous step.
(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
}
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": []
  }
}
To monitor the status of the job, note down the job_id from the response that you received in the previous step.
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
}
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.
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
     }
   }
  ]
}
If required, restart the target servers.
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
}

Example 2: The following example describes how to use the REST APIs to deploy Errata type patches on servers running Red Hat Enterprise Linux 7.5 operating systems. The servers are not listed in any smart groups. There are 100 servers to be deployed. The analysis and remediation job must be executed weekly on every Saturday starting July 01, 2019. Also, the job status must be notified through an email message. Also, ErrataNameToBeExcluded is not to be included in the list of patches to be deployed.

Prerequisites:

Red Hat Enterprise Linux 7.5 catalogs must be created.
Email notification must be configured on .

Steps:

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"
   }
}
}
Authorize the session by using the Authorize button.

Click here to view steps to authorize the session.
Get the list of catalogs for the Red Hat 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=redhat
Response:
{
"catalogs": [
    {
     "name": "RedHat Linux Patch Catalog",
     "description": "This is an example Patching Catalog for Redhat Linux Patching.",
     "type": {
       "id": 5020,
       "name": "Red Hat Catalog"
      },
     "group": {
       "id": 2000183,
       "name": "Patch Catalogs",
       "path": "/Workspace/Patch Catalogs"
      },
     "id": 2000212,
     "acl_id": 2000065
    },
    {
     "name": "API_Rhel7_Catalog",
     "description": "",
     "type": {
       "id": 5020,
       "name": "Red Hat Catalog"
      },
     "group": {
       "id": 2000216,
       "name": "AutomationPatching",
       "path": "/AutomationPatching"
      },
     "status": {
       "progress_status": "complete",
       "is_usable": true,
       "result": {
         "status": "passed",
         "summary": [
            {
             "object_type": {
               "id": 68,
               "name": "RPM Installable"
              },
             "status": "ADDED",
             "total_count": 12
            },
            {
             "object_type": {
               "id": 68,
               "name": "RPM Installable"
              },
             "status": "DOWNLOADED",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 68,
               "name": "RPM Installable"
              },
             "status": "UPDATED",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 68,
               "name": "RPM Installable"
              },
             "status": "OBSOLETED",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 68,
               "name": "RPM Installable"
              },
             "status": "FAILED",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 68,
               "name": "RPM Installable"
              },
             "status": "FAILED_TO_DOWNLOAD",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 68,
               "name": "RPM Installable"
              },
             "status": "INVALID_URL",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 305,
               "name": "Red Hat Errata Installable"
              },
             "status": "ADDED",
             "total_count": 1
            },
            {
             "object_type": {
               "id": 305,
               "name": "Red Hat Errata Installable"
              },
             "status": "UPDATED",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 305,
               "name": "Red Hat Errata Installable"
              },
             "status": "OBSOLETED",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 305,
               "name": "Red Hat Errata Installable"
              },
             "status": "FAILED",
             "total_count": 0
            }
          ]
        },
       "job_run_id": 229
      },
     "id": 2000217,
     "acl_id": 2000070
    },
    {
     "name": "API_Rhel7_Failed_Catalog",
     "description": "",
     "type": {
       "id": 5020,
       "name": "Red Hat Catalog"
      },
     "group": {
       "id": 2000216,
       "name": "AutomationPatching",
       "path": "/AutomationPatching"
      },
     "status": {
       "progress_status": "complete",
       "is_usable": false,
       "result": {
         "status": "failed",
         "summary": [
            {
             "object_type": {
               "id": 68,
               "name": "RPM Installable"
              },
             "status": "ADDED",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 68,
               "name": "RPM Installable"
              },
             "status": "DOWNLOADED",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 68,
               "name": "RPM Installable"
              },
             "status": "UPDATED",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 68,
               "name": "RPM Installable"
              },
             "status": "OBSOLETED",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 68,
               "name": "RPM Installable"
              },
             "status": "FAILED",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 68,
               "name": "RPM Installable"
              },
             "status": "FAILED_TO_DOWNLOAD",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 68,
               "name": "RPM Installable"
              },
             "status": "INVALID_URL",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 305,
               "name": "Red Hat Errata Installable"
              },
             "status": "ADDED",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 305,
               "name": "Red Hat Errata Installable"
              },
             "status": "UPDATED",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 305,
               "name": "Red Hat Errata Installable"
              },
             "status": "OBSOLETED",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 305,
               "name": "Red Hat Errata Installable"
              },
             "status": "FAILED",
             "total_count": 0
            }
          ]
        },
       "job_run_id": 232
      },
     "id": 2000242,
     "acl_id": 2000070
    },
    {
     "name": "API_Rhel6_Catalog",
     "description": "",
     "type": {
       "id": 5020,
       "name": "Red Hat Catalog"
      },
     "group": {
       "id": 2000216,
       "name": "AutomationPatching",
       "path": "/AutomationPatching"
      },
     "id": 2000350,
     "acl_id": 2000070
    },
    {
     "name": "API_Rhel5_Catalog",
     "description": "",
     "type": {
       "id": 5020,
       "name": "Red Hat Catalog"
      },
     "group": {
       "id": 2000216,
       "name": "AutomationPatching",
       "path": "/AutomationPatching"
      },
     "status": {
       "progress_status": "complete",
       "is_usable": true,
       "result": {
         "status": "passed",
         "summary": [
            {
             "object_type": {
               "id": 68,
               "name": "RPM Installable"
              },
             "status": "ADDED",
             "total_count": 17331
            },
            {
             "object_type": {
               "id": 68,
               "name": "RPM Installable"
              },
             "status": "DOWNLOADED",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 68,
               "name": "RPM Installable"
              },
             "status": "UPDATED",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 68,
               "name": "RPM Installable"
              },
             "status": "OBSOLETED",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 68,
               "name": "RPM Installable"
              },
             "status": "FAILED",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 68,
               "name": "RPM Installable"
              },
             "status": "FAILED_TO_DOWNLOAD",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 68,
               "name": "RPM Installable"
              },
             "status": "INVALID_URL",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 305,
               "name": "Red Hat Errata Installable"
              },
             "status": "ADDED",
             "total_count": 3182
            },
            {
             "object_type": {
               "id": 305,
               "name": "Red Hat Errata Installable"
              },
             "status": "UPDATED",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 305,
               "name": "Red Hat Errata Installable"
              },
             "status": "OBSOLETED",
             "total_count": 0
            },
            {
             "object_type": {
               "id": 305,
               "name": "Red Hat Errata Installable"
              },
             "status": "FAILED",
             "total_count": 0
            }
          ]
        },
       "job_run_id": 273
      },
     "id": 2000351,
     "acl_id": 2000070
    },
    {
     "name": "API_Rhel4_Catalog",
     "description": "",
     "type": {
       "id": 5020,
       "name": "Red Hat Catalog"
      },
     "group": {
       "id": 2000216,
       "name": "AutomationPatching",
       "path": "/AutomationPatching"
      },
     "id": 2000352,
     "acl_id": 2000070
    }
  ],
"total_records": 6
}
Note down the Catalog ID for API_Rhel7_Catalog catalog from the response that you received in the previous step.
(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/2000217
Response:
{
"schedule_id": 266
}
Create a patching job for the specific Catalog ID by using the POST/api/v1/patching-jobs API. Do the following:

Click here to view the request and response.

Request:
{
"name": "patch_job_example",
"description": "PAJ With Schedules Once",
"group": {
"id": 2000285
},
"catalog": {
"id": 2000217
},
"max_parallel_targets": 0,
"execution_override": false,
"analysis": {
"redhat": {
"mode": "install",
"package_name_options": "By_Complete_Package_Name",
"list": {
"patch_list": {
"include": [41, 44, 45, 46, 49, 50],
"exclude": [42]
}
}
}
},
"targets": {
"servers": [{
"id": 5
}, {
"name": "Restlinagt2"
}, {
"name": "Restlinagt3"
}, {
"name": "Restlinagt4"
}]
},
"execute_now": false,
"schedules": [{
"weekly": {
"time": "10:15",
"frequency": 1,
"days": [
"Saturday"
]
},
"timezone": "Asia/Calcutta",
"priority": "CRITICAL"
}]
}
Response:
{
"id": {
   "job_id": 1254,
   "job_version": 1
  },
"name": "patch_job_example",
"description": "PAJ With Schedules Once",
"group": {
   "id": 2000285,
   "name": "PAJ_Redhat_17",
   "path": "/PAJ_Redhat_17"
  },
"catalog": {
   "id": 2000217,
   "name": "API_Rhel7_Catalog",
   "path": "/AutomationPatching/API_Rhel7_Catalog"
  },
"max_parallel_targets": 0,
"execution_override": false,
"analysis": {
   "redhat": {
     "package_name_options": "By_Complete_Package_Name",
     "list": {
       "patch_list": {
         "include": [
           49,
           50,
           41,
           44,
           45,
           46
          ],
         "exclude": [
           42
          ]
        },
       "patch_group_list": {
         "include": [],
         "exclude": []
        }
      },
     "mode": "install"
    }
  },
"targets": {
   "servers": [
      {
       "id": 5,
       "name": "Restlinagt1"
      },
      {
       "id": 10,
       "name": "Restlinagt2"
      },
      {
       "id": 11,
       "name": "Restlinagt3"
      },
      {
       "id": 12,
       "name": "Restlinagt4"
      }
    ]
  },
"schedules": [
    {
     "id": 268,
     "weekly": {
       "time": "10:15",
       "frequency": 1,
       "days": [
         "Saturday"
        ]
      },
     "timezone": "Asia/Calcutta",
     "priority": "CRITICAL"
    }
  ],
"acl": {
   "acl_id": 2000068,
   "aces": [
      {
       "role_id": 1000010,
       "role_name": "BLAdmins",
       "authorization_id": 10000,
       "authorization_name": "PatchingJob.*"
      }
    ],
   "acl_policies": []
  }
}
To monitor the status of the job, note down the job_id from the response that you received in the previous step.
Get the latest job_run_id of the specific job by using the GET : api/v1/patching-jobs/{id}/jobruns API. Need info

Click here to view the request and response.

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

Need info
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.
Monitor the job results by using the GET : api/v1/patching-jobs/{id}/jobruns/{run_id}/results API. Need info

Click here to view the request and response.

Request URL: https://<hostname>:<port>/rest/api/v1/patching-jobs/1003/jobruns/113/results Need info
Response:
Need info
If required, restart the target servers.
Validate the deployment by running the analysis job by using the PATCH: api/v1/patching-jobs/{id} API. Need info

Click here to view the request and response.

Request URL: https://<hostname>:<port>/rest/api/v1/patching-jobs/Need info
Response:
{
"schedule_id": Need info
}

Examples of REST APIs

On this page