×
 
 
  •  
$helper.renderConfluenceMacro('{bmc-global-announcement:$space.key}')

   

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.
BMC Helix Operations Management 22.3 Managing policies, event data, and metric data with REST APIs

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 Open link

Related topic

PATROL Script Language overview and functions Open link


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

POST /agent_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/

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. Open link

Parameter details

Parameter NameValue TypeLocated InMandatoryDescription
nameStringbodyYes

A name for the command.

The maximum length is 200 characters. The following special characters are allowed:

  • - (hyphen)
  • , (comma)
  • _ (underscore)
  • & (ampersand)
  • ; (semi colon)
descriptionStringbodyNoA description for the command.
commandStringbodyYes

The PSL command body.

Before sending the command, ensure that you replace double quotation marks "" with the value &quot;.

Example

Actual command

" print(pconfig("GET","/AgentSetup/historyRetentionPeriod")); "

 Command in the REST body

" print(pconfig(&quot;GET&quot;,&quot;/AgentSetup/historyRetentionPeriod&quot;)); "

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>
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. Open link

Parameter details

Parameter NameValue TypeLocated InMandatoryDescription
nameStringbodyYesA name for the command.
descriptionStringbodyNoA description for the command.
commandStringbodyYes

The PSL command body.

Before sending the command, ensure that you replace double quotation marks "" with the value &quot;.

Example

Actual command

" print(pconfig("GET","/AgentSetup/historyRetentionPeriod")); "

 Command in the REST body

" print(pconfig(&quot;GET&quot;,&quot;/AgentSetup/historyRetentionPeriod&quot;)); "
pslidStringpathYes

The PSL command ID.

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>

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. Open link

Parameter details

Parameter NameValue TypeLocated InMandatoryDescription
pslid or nameStringpathYesThe ID or name of the PSL command.
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/
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. Open link

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>
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. Open link

Parameter details

Parameter NameValue TypeLocated InMandatoryDescription
pslidStringpathYesThe PSL command ID.

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

Was this page helpful? Yes No Submitting... Thank you
Last modified by Mukta Kirloskar on Jul 26, 2022
swagger developing api reference development

Comments

Log in or register to comment.

Managing global variables with REST APIs
Managing time frames for event policies with REST APIs
© Copyright 2020-2022 BMC Software, Inc.
Legal notices

Powered by Atlassian Confluence and Scroll Viewport

© Copyright 2005-2024 BMC Software, Inc. Use of this site signifies your acceptance of BMC’s Terms of Use . BMC, the BMC logo, and other BMC marks are assets of BMC Software, Inc. These trademarks are registered and may be registered in the U.S. and in other countries.