This documentation supports an earlier version of BMC Helix Operations Management.To view the documentation for the latest version, select 23.2 from the Product version picker.

Managing the Agent Query Tool PSL commands with REST APIs

The following section provides a list of supported endpoints and an overview about running these endpoints. Before you run an endpoint, you must authenticate yourself. For more information, see Access and authentication for the REST API

Related topic

PATROL Script Language overview and functions


You can create, update, delete, and retrieve the Agent Query Tool (AQT) PATROL Script Language (PSL) commands by running APIs. 

POST /agent_commands
Create a PSL command
Request URL
 https://<BMC Helix Portal URL>/acs/api/v1.0/agent_commands/
Example request URL
 https://HostA.bmc.com/acs/api/v1.0/agent_commands/

You can create a PSL command even if the command:

  • Contains a special character in the name or the body
  • Contains blank spaces in the name
  • Contains double quotation marks "" in the body
  • Is longer than 1056 characters

You can also create multiple PSL commands with the same body with different names.

Request Header
Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions about obtaining the JWT token, see Access and authentication for the REST API.

Parameter details


Note

In the command body, ensure the following:

  • Use the escape character \ before a backslash '\' or before the '\\n' character.
    For example:
    \\
    \\\n
  • Use the value &quot; instead of double quotation marks "".

Request body

{
"name": "string",
"description": "string",
"command": "string"
}

Example request body

{
"name": "History Retention Period",
"description": "To Get The History Retention Period",
"command": " print(pconfig(&quot;GET&quot;,&quot;/AgentSetup/historyRetentionPeriod&quot;)); "
}

CURL request body

curl --location --request POST 'https://<BMC Helix Portal-url>/acs/api/v1.0/agent_commands/' \
--header 'Authorization: Bearer <JWT-Token>' \
--header 'Content-Type: application/json' \
--data '{
    "name": "command Name",
   "description": "Describe usage of command",
   "command": " PSL command  "
}'

CURL example request body

curl --location --request POST 'https://acme-trial.bmc.com/acs/api/v1.0/agent_commands/' \
--header 'Authorization: Bearer abc' \
--header 'Content-Type: application/json' \
--data '{
"name": "History Retention Period",
"description": "To Get The History Retention Period",
"command": " print(pconfig(&quot;GET&quot;,&quot;/AgentSetup/historyRetentionPeriod&quot;)); "
}'


Successful response

Success code: 200

{
'AgentCommand_Id': [
{
'id': 'cc495a2d-6bff-4be4-b85c-6e850582b660'
}
],
'message': 'Agent command created successfully'
}


Unsuccessful responses

Status code: 400

Scenario 1: The command name is empty or the command already exists.

Either Name/Command is null or Name already exist

Scenario 2: Invalid command body

Unrecognized field "name1" (class com.bmc.truesight.saas.acs.aqt.model.AQTRequest), not marked as ignorable


Back to top

put /agent_commands/<pslid>
Edit a PSL command
Request URL
 https://<BMC Helix Portal URL>/acs/api/v1.0/agent_commands/<pslid>
Example request URL
 https://HostA.bmc.com/acs/api/v1.0/agent_commands/3bd2140c-e2c4-4c9a-b04b-c4593841cf31
Request Header
Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions about obtaining the JWT token, see Access and authentication for the REST API.

Parameter details

Request body

{
"name": "string",
"description": "string",
"command": "string"
}

Example request body

{
 "name": "Agent Information Command",
 "description": "Agent Information Details",
 "command": "print(&quot;Host = &quot;.get(&quote;/name&quot;).&quot;IP address = &quot;.get(&quot;/ipAddress&quot;).&quot;OS Version = &quot;.get(&quot;/osName&quot;)." ".get(&quot;/osVersion&quot;));"
}

CURL request body

curl --location --request PUT 'https://<BMC Helix Portal-url>/acs/api/v1.0/agent_commands/<pslid>' \
--header 'Authorization: Bearer <JWT-Token>' \
--header 'Content-Type: application/json' \
--data '{
    "name": "command Name",
   "description": "Describe usage of command",
   "command": "PSL command"
}'

CURL example request body

curl --location --request PUT 'https://acme-trial.bmc.com/acs/api/v1.0/agent_commands/8329fa78-dbad-4135-9325-fe8cfe04458a' \
--header 'Authorization: Bearer abc' \
--header 'Content-Type: application/json' \
--data '{
"name": "Agent Information Command",
"description": "Agent Information Details",
"command": "print(&quot;Host = &quot;.get(&quot;/name&quot;).&quot;IP address = &quot;.get(&quot;/ipAddress&quot;).&quot;OS Version = &quot;.get(&quot;/osName&quot;).&quot; &quot;.get(&quot;/osVersion&quot;));"
}'


Successful response

Success code: 200

{
'user_name': 'admin',
'name': 'rhqokhmbbysffluytmbjeucap',
'description': 'fhqcxmslrgvafcnqplfhawkse',
'command': 'pwmztgemhqjrxnetepmizdjiq',
'creation_time': '2022-06-17T13:08:52.296156',
'modified_time': '2022-06-17T13:08:53.741090',
'id': 'cc495a2d-6bff-4be4-b85c-6e850582b660'
}


Unsuccessful response

Scenario 1: Invalid command ID

Error code: 404

Agent Command not found for 8ec8030e-c08a-420c-bb09-d499082a0fe0

Scenario 2: Unauthorized access

Error code: 401

Authentication Failed!!!

Back to top

DELETE /agent_commands/<pslid>
Delete a PSL command based on the command ID or name

To delete a PSL command by ID, add ?type=id at the end of the command.

Request URL
 https://<BMC Helix Portal URL>/acs/api/v1.0/agent_commands/<pslid>?type=id
Example request URL for deleting a command by ID
 https://HostA.bmc.com/acs/api/v1.0/agent_commands/cc495a2d-6bff-4be4-b85c-6e850582b660?type=id

To delete a PSL command by name, add ?type=name at the end of the command.

Request URL
 https://<BMC Helix Portal URL>/acs/api/v1.0/agent_commands/<pslid>?type=name
Example request URL for deleting a command by name
 https://HostA.bmc.com/acs/api/v1.0/agent_commands/cc495a2d-6bff-4be4-b85c-6e850582b660?type=name
Request Header
Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions about obtaining the JWT token, see Access and authentication for the REST API.

Parameter details

CURL request body

Delete by ID
curl --location --request DELETE 'https://<BMC Helix Portal-url>/acs/api/v1.0/agent_commands/<pslid>?type=id' \
--header 'Authorization: Bearer <JWT-Token>' \
--data ''


Delete by name
curl --location --request DELETE 'https://<BMC Helix Portal-url>/acs/api/v1.0/agent_commands/<agent_command_name>?type=name' \
--header 'Authorization: Bearer <JWT-Token>' \
--data ''

CURL example request body

Delete by ID
curl --location --request DELETE 'https://acme-trial.bmc.com/acs/api/v1.0/agent_commands/8329fa78-dbad-4135-9325-fe8cfe04458a?type=id' \
--header 'Authorization: Bearer abc' \
--data ''


Delete by name
curl --location --request DELETE 'https://acme-trial.bmc.com/acs/api/v1.0/agent_commands/Agent Information Command?type=name' \
--header 'Authorization: Bearer abc' \
--data ''

Successful response

Success code: 200

Agent command deleted.


Unsuccessful response

Scenario 1: Unauthorized access

Error code: 401

Authentication Failed!!!

Back to top

GET /agent_commands/
Get a list of all PSL commands
Request URL
 https://<BMC Helix Portal URL>/acs/api/v1.0/agent_commands/
Example request URL
 https://HostA.bmc.com/acs/api/v1.0/agent_commands/
Request Header
Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions about obtaining the JWT token, see Access and authentication for the REST API.

CURL request body

curl --location --request GET 'https://<BMC Helix Portal-url>/acs/api/v1.0/agent_commands/' \
--header 'Authorization: Bearer <JWT-Token>' \
--data ''

CURL example request body

curl --location --request GET 'https://acme-trial.dsmlab.bmc.com/acs/api/v1.0/agent_commands/' \
--header 'Authorization: Bearer abc' \
--data ''

Successful response

Success code: 200

[
  {
   "user_name": "system",
   "name": "All pconfig variables",
   "description": "oob",
   "command": "print(system("pconfig +get -port ".get("/tcpPort")));",
   "creation_time": "2022-06-25 08:55:42.049397+00",
   "modified_time": null,
   "id": "5968cca1-81c8-41fd-9bdc-85ddcfd671c2"
  },
  {
   "user_name": "system",
   "name": "Disabled KMs",
   "description": "oob",
   "command": "print(pconfig("GET","/AgentSetup/disabledKMs"));",
   "creation_time": "2022-06-25 08:55:42.049397+00",
   "modified_time": null,
   "id": "fd707e69-6c69-4984-b264-caf22447e998"
  },
  {
   "user_name": "system",
   "name": "Active/ Running KMs details",
   "description": "oob",
   "command": "print(system("%DUMP KM_LIST"));",
   "creation_time": "2022-06-25 08:55:42.049397+00",
   "modified_time": null,
   "id": "6e32bca0-4995-4d78-b14a-29df1bf80922"
  },
  {
   "user_name": "system",
   "name": "Agent Information",
   "description": "oob",
   "command": "print("Host = ".get("/name")."\\nIP address = ".get("/ipAddress")."\\nPort = ".get("/tcpPort")."\\nVersion = ".get("/patrolVersion")."\\nOS Version = ".get("/osName")." ".get("/osVersion"));",
   "creation_time": "2022-06-25 08:55:42.049397+00",
   "modified_time": null,
   "id": "968aa00f-6830-4c10-ae82-67baef43b278"
  },
  {
   "user_name": "system",
   "name": "History Retention",
   "description": "oob",
   "command": "print(pconfig("GET","/AgentSetup/historyRetentionPeriod"));",
   "creation_time": "2022-06-25 08:55:42.049397+00",
   "modified_time": null,
   "id": "d917aef2-8750-422f-a7ce-3fa72e45b04c"
  },
  {
   "user_name": "system",
   "name": "Preloaded KMs - Policy configured",
   "description": "oob",
   "command": "printf("Policy Configured:\\n%s\\n",pconfig("GET","/ConfigData/AgentSetup/preloadedKMs"));",
   "creation_time": "2022-06-25 08:55:42.049397+00",
   "modified_time": null,
   "id": "d8965824-ddae-4911-acc4-9af152db6315"
  },
  {
   "user_name": "system",
   "name": "Preloaded KMs - Locally configured",
   "description": "oob",
   "command": "printf("Locally Configured:\\n%s\\n",pconfig("GET","/AgentSetup/preloadedKMs"));",
   "creation_time": "2022-06-25 08:55:42.049397+00",
   "modified_time": null,
   "id": "ca5c3df7-ae86-405c-acfc-7d5af852adbc"
  },
  {
   "user_name": "system",
   "name": "Last 20 Parameter Alarm/Warning Events",
   "description": "oob",
   "command": "print("The result of the query:(Earliest First)\\\\n\\\\n".event_query("20","\\n\\n","TimeStamp: %{EV_TIME} Event id: %{EV_ID} Event type: %{EV_TYPE} Event description:%{EV_DESC}\\n","","","O", "A,W","","","", "-/-", "11",""). "\\\\n");",
   "creation_time": "2022-06-25 08:55:42.049397+00",
   "modified_time": null,
   "id": "01561e74-74ff-4526-a6c4-f5908c0562d0"
  },
  {
   "user_name": "system",
   "name": "Refresh Parameters",
   "description": "oob",
   "command": "execute("OS","%REFRESH_ALL_PARAMS");",
   "creation_time": "2022-06-25 08:55:42.049397+00",
   "modified_time": null,
   "id": "0771e882-238e-467a-82c4-646d19fe9d89"
  },
  {
   "user_name": "system",
   "name": "Force Discovery",
   "description": "oob",
   "command": "execute("OS","%REFRESH_APPL_DISC");",
   "creation_time": "2022-06-25 08:55:42.049397+00",
   "modified_time": null,
   "id": "c8d7b233-bfab-4818-a8d0-d97272e27c13"
  },
  {
   "user_name": "system",
   "name": "PATROL SID Report",
   "description": "oob",
   "command": "outputLine="PATROL SID Report:\\\\n";instanceCount=int(0);parameterCount=int(0);foreach line KM (get_vars("","nodes")) {displayName=get("/".KM."/MetaKMDisplayName");kmName=get("/".KM."/name");if (length(displayName)){outputLine=outputLine."================================================================================================\\\\n|MONITOR TYPE:".displayName."(".kmName."):\\\\n================================================================================================\\\\n";foreach line instance (get("/".KM."/instances")) {instanceCount=int(instanceCount+1);parameterCount=int(parameterCount + lines(get_vars("/".KM."/".instance,"nodes")) - 2);instName=get("/".KM."/".instance . "/name");outputLine=outputLine.sprintf("|\\\\tNAME:%s\\\\t SID:%s\\\\n", instName, instance);}}}outputLine=outputLine."\\\\n\\\\nAgent currently has:\\\\n\\\\tInstances: ".instanceCount."\\\\n\\\\tParameters: ".parameterCount."\\\\n";print(outputLine);",
   "creation_time": "2022-06-25 08:55:42.049397+00",
   "modified_time": null,
   "id": "7f9b81db-e501-47fe-a15b-951f8df05cd1"
  },
  {
   "user_name": "system",
   "name": "Mapped Device Report",
   "description": "oob",
   "command": "x=get_vars("","nodes");output="\\\\n=========================================================================\\\\n| Mapped Device Report:\\\\n=========================================================================\\\\n";foreach line KM (x) {cdmName=get("/".KM."/MetaKMCDMClassName");if (cdmName=="BMC_ComputerSystem") { foreach line instance (get("/".KM."/instances")) { displayName=get("/".KM."/MetaKMDisplayName");kmName=get("/".KM."/name"); mdFQDN=get("/".KM."/".instance."/MetaFQDN"); mdTID=get("/".KM."/".instance."/MetaTokenID"); if (length(mdFQDN)>0 && length(mdTID)>0) { output=output."| Mapped device:".mdFQDN."\\\\n|\\\\tMonitor type:".displayName."(".kmName.")\\\\n|\\\\tToken ID:".mdTID."\\\\n|\\\\n";}}}} print(output."=========================================================================\\\\n\\\\n");",
   "creation_time": "2022-06-25 08:55:42.049397+00",
   "modified_time": null,
   "id": "e6968cbc-1e7b-4d30-88c4-5ee3464c8739"
  },
  {
   "user_name": "system",
   "name": "Preloaded KMs - All -Policy+Local",
   "description": "oob",
   "command": "printf("Merged List:\\n%s,%s\\n\\n",trim(pconfig("GET","/AgentSetup/preloadedKMs"),"\\\\n"),pconfig("GET","/ConfigData/AgentSetup/preloadedKMs")."\\n");",
   "creation_time": "2022-06-25 08:55:42.049397+00",
   "modified_time": null,
   "id": "b7a1109f-41a6-4e5f-ad87-ed2d66f4552f"
  },
  {
   "user_name": "system",
   "name": "Generate Namespace",
   "description": "oob",
   "command": "outputFileName=replace(get("/agentLogPath"),".errs",".namespace");outputFile=fopen(outputFileName,"w");write(outputFile,"\\n\\n===========================================================================\\n");write(outputFile,"| Global variables:                                                       |\\n");write(outputFile,"===========================================================================\\n");foreach line attr (get_vars("/","leaves")) { if ( attr == "AgentSetup" || attr == "EventSetup" ||attr == "ConfigData" || attr == "___tuning___" || attr == "snmp" || attr == "__self__" ) {  next; } else {  value=replace(get("/".KM."/".attr),"\\n","\\n\\t"); } write(outputFile,attr."(".value.")\\n");}foreach line KM ("AgentSetup\\nConfigData\\nEventSetup\\n".get_vars("","subnodes")) { write(outputFile,"\\n\\n===========================================================================\\n"); write(outputFile,"Application class: ".KM."\\n"); write(outputFile,"===========================================================================\\n");     foreach line attr (get_vars("/".KM,"leaves")) {         if ( attr == "AgentSetup" || attr == "EventSetup" ||attr == "ConfigData" || attr == "___tuning___" || attr == "snmp" || attr == "__self__" ) {             next;         }         value=replace(get("/".KM."/".attr),"\\n","\\n\\t");         write(outputFile,"|--".attr."(".value.")\\n");     }  foreach line instance (get_vars("/".KM,"subnodes")) {  write(outputFile,"|\\n|-- INSTANCE:".instance."\\n");     foreach line inst_attr (get_vars("/".KM."/".instance,"leaves")) {      if ( inst_attr == "AgentSetup" || inst_attr == "EventSetup" ||inst_attr == "ConfigData" || inst_attr == "___tuning___" || inst_attr == "snmp" || attr == "__self__" ) {    next;   }      inst_attr_value=replace(get("/".KM."/".instance."/".inst_attr),"\\n","\\n\\t\\t");   write(outputFile,"    |--".inst_attr."(".inst_attr_value.")\\n");  }     foreach line param (get_vars("/".KM."/".instance,"subnodes")) {      if ( param == "AgentSetup" || param == "EventSetup" ||param == "ConfigData" || param == "___tuning___" || param == "snmp" || attr == "__self__" ) {    next;   }   write(outputFile,"    |\\n    |--PARAMETER:".param."\\n");   foreach line param_attr (get_vars("/".KM."/".instance."/".param,"leaves")) {    param_value=replace(get("/".KM."/".instance."/".param."/".param_attr),"\\n","\\n\\t\\t\\t");    write(outputFile,"       |--".param_attr."(".param_value.")\\n");   }  } }}close(outputFile,0);if (get("/appType")=="NT") {cmd="TYPE \\\\"".outputFileName."\\\\"";}else{cmd="cat ".outputFileName;} print("Namespace report generated in ".outputFileName."\\n".system(cmd));",
   "creation_time": "2022-06-29 09:34:41.818111+00",
   "modified_time": null,
   "id": "ec0fdb10-bf1c-4e5d-a3c3-11a7db057d44"
  }
]


Unsuccessful response

Scenario 1: Unauthorized access

Error code: 401

Authentication Failed!!!

Back to top

get /agent_commands/<pslid>
Get a PSL command based on the command ID
Request URL
 https://<BMC Helix Portal URL>/acs/api/v1.0/agent_commands/<pslid>
Example request URL
 https://HostA.bmc.com/acs/api/v1.0/agent_commands/cc495a2d-6bff-4be4-b85c-6e850582b660
Request Header
Content-Type: application/json
Authorization: Bearer <JWT_token>

For instructions about obtaining the JWT token, see Access and authentication for the REST API.

Parameter details

CURL request body

curl --location --request PUT 'https://<BMC Helix Portal-url>/acs/api/v1.0/agent_commands/<pslid>' \
--header 'Authorization: Bearer <JWT-Token>' \
--header 'Content-Type: application/json' \

CURL example request body

curl --location --request PUT 'https://acme-trial.bmc.com/acs/api/v1.0/agent_commands/8329fa78-dbad-4135-9325-fe8cfe04458a' \
--header 'Authorization: Bearer abc' \
--header 'Content-Type: application/json' \

Successful response

Success code: 200

{
   "userName": admin,
   "pslCommandName": "History Retention Period",
   "displayText": "History Retention Period",
   "pslCommand": " print(pconfig("GET","/AgentSetup/historyRetentionPeriod")); ",
   "currentTime": "2022-05-16T10:25:45.162861",
   "modifiedTime": "2022-05-16T10:25:45.162861",
   "pslid": "2a4da4de-a53f-4f8b-aa32-a67381ab6850"
}


Unsuccessful response

Scenario 1: Unauthorized access

Error code: 401

Authentication Failed!!!

Back to top

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*