Help Menu

This help page is for version 5.7. The latest available help is for version 8.0.

External API

PA Server Monitor has a simple API for automating some basic operations.

Security

To protect the system from un-authorized requests, there are two security precautions that are required:

Requests are made via HTTPS. The format of the requests is:

HTTPS://{server}:{port}?API={command}&KEY={API Key}

Additional optional parameters can be appended to the URL using the pattern:

&{param_name}={value}

Return Values

All API commands return data as simple text. Successful commands return as XML, or in the following format:

:START:
{returned data
can be multiple lines}
:END:

All errors are returned as:

:ERROR:{error text}

API Commands

Below are the supported commands. The command name should be inserted where {command} is shown in the example above.

GET_SERVER_LIST

Returns a list of servers and the group that the server is in. The XML version also shows the computer's internal ID.

Optional Parameters
XML = {0|1} - defaults to 0

Example

https://server:81?API=GET_SERVER_LIST&KEY=msa8gbk4j78dbglaj

Output (server|group^group)

:START:
DNVISTA|Servers/Devices
192.168.2.5|Servers/Devices
POWERADMIN.COM|Servers/Devices^Boston
OPSMON02|Servers/Devices^Servers^Office
ARCHIVE|Servers/Devices
:END:

XML Example

https://server:81?API=GET_SERVER_LIST&KEY=msa8gbk4j78dbglaj&XML=1

XML Output

<?xml version="1.0" ?>
<servers>
  <server name="DNVISTA" group="Servers/Devices^Boston^Servers" id="1" groupID="1" alias="DNVISTA" status="ok" />
  <server name="192.168.2.5" group="Servers/Devices^Kansas City" id="2" groupID="2" alias="EXCHANGE" status="maintenance" />
  <server name="POWERADMIN.COM" group="Servers/Devices^External" id="4" groupID="3" alias="POWERADMIN.COM" status="disabled" />
  <server name="OPSMON02" group="Servers/Devices^Boston^Servers" id="5" groupID="1" alias="OPS" status="unlicensed" />
  <server name="ARCHIVE" group="Servers/Devices^Boston^Servers" id="8" groupID="1" alias="ARCHIVE" status="sat_disconnected" />
</servers>

Note that all possible values of 'status' are shown above

GET_GROUP_LIST

Returns a list of groups, with their name, full path name, group ID, and group ID for the group's parent.

Optional Parameters
XML = {0|1} - defaults to 0

Example

https://server:81?API=GET_GROUP_LIST&KEY=msa8gbk4j78dbglaj

Output (name|full path|id|parentID)

:START:
Servers/Devices|Servers/Devices|0|-1
Boston|Servers/Devices^Boston|1|0
Office|Servers/Devices^Office|2|0
Dev|Servers/Devices^Office^Dev|3|2
:END:

XML Example

https://server:81?API=GET_GROUP_LIST&KEY=msa8gbk4j78dbglaj&XML=1

XML Output

<?xml version="1.0" ?>
<groups>
  <group name="Servers/Devices" path="Servers/Devices" id="0" parentID="-1" />
  <group name="Boston" group="Servers/Devices^Boston" id="1" parentID="0" />
  <group name="Office" group="Servers/Devices^Office" id="2" parentID="0" />
  <group name="Dev" group="Servers/Devices^Office^Dev" id="3" parentID="2" />
</groups>

GET_MONITOR_INFO

Returns information about all monitors owned by a particular computer.

Required Parameters
CID - Computer ID for the computer to target for the operation. Computer IDs can be obtained via the GET_SERVER_LIST (XML output) above.

Optional Parameters
FORMAT_DATE - 0 to always output as dd-mm-yyyy hh:mm:ss (24 hour hh), or 1 to use the same format that the existing reports use (which can be customized). Defaults to 0.

Example

https://server:81?API=GET_MONITOR_INFO&KEY=msa8gbk4j78dbglaj&CID=371
&FORMAT_DATE=1

Output (XML)

<?xml version="1.0" ?>
<monitors>
  <monitor id="13" status="OK" depends_on="" title="Check Free Disk Space" lastRun="16-10-2010 5:54:10" nextRun="16-10-2010 11:54:10" errText="" errorActionIDs="1,3,8" fixedActionIDs="" />
  <monitor id="74" status="Alert" depends_on="132,5" title="Ping OPSMON02" lastRun="16-10-2010 6:25:12" nextRun="16-10-2010 6:26:12" errText="OPSMON02 is not responding to ping requests [in error for 2m 3s]" errorActionIDs="7,3" fixedActionIDs="3" />
</monitors>

Pro Tip: If you set the following registry value, you can see Group, Server and Monitor IDs directly in the navigation pane of the Console.

HKEY_LOCAL_MACHINE\software\PAServerMonitor
xShowIDs = 1
GET_ACTION_INFO

Returns a list describing all the actions in the system (these IDs are used in the errorActionIDs and fixedActionIDs attributes returned from GET_MONITOR_INFO

Example

https://server:81?API=GET_ACTION_INFO&KEY=msa8gbk4j78dbglaj

Output (XML)

<?xml version="1.0" ?>
<actions>
  <action id="1" type="Message Box" typeID="3" title="Message Box" />
  <action id="2" type="Write to a Text Log File" typeID="6" title="Write to ServerEvents.txt log file" />
  <action id="6" type="Start, Stop or Restart a Service" typeID="5" title="Restart stopped service on monitored computer" />
</actions>

START_MAINTENANCE

Put the server into immediate maintenance mode.

Required Parameters
CID - Computer ID for the computer to target for the operation. Computer IDs can be obtained via GET_SERVER_LIST (XML output) above.
- or -
GID - Group ID for the group that contains target computers (including those in child-groups). Group IDs can be obtained from GET_GROUP_LIST.
- or -
MID - Monitor ID for the specific monitor that should be affected. Monitor IDs can be obtained from GET_MONITOR_INFO.

MINUTES - time in minutes that the server should remain in maintenance mode before it automatically reverts to normal monitoring

Example

https://server:81?API=START_MAINTENANCE&KEY=msa8gbk4j78dbglaj&CID=37&MINUTES=15

Output

:OK:

END_MAINTENANCE

Put the server back into normal monitoring mode.

Required Parameters
CID - Computer ID for the computer to target for the operation. Computer IDs can be obtained via GET_SERVER_LIST (XML output) above.
- or -
GID - Group ID for the group that contains target computers (including those in child-groups). Group IDs can be obtained from GET_GROUP_LIST.
- or -
MID - Monitor ID for the specific monitor that should be affected. Monitor IDs can be obtained from GET_MONITOR_INFO.

Example

https://server:81?API=END_MAINTENANCE&KEY=msa8gbk4j78dbglaj&CID=37

Output

:OK:

RUN_NOW

Request the specified monitor be run immediately

Required Parameters
MID - Monitor ID for the monitor to run immediately. Monitor IDs can be obtained from GET_MONITOR_INFO above.

Optional Parameters
FORCE - 1 to run the monitor even if it's disabled or the server is in maintenance. Defaults to 0

Example

https://server:81?API=RUN_NOW&KEY=msa8gbk4j78dbglaj&MID=4721&FORCE=1

Output

:OK:

DISCOVERY_CONFIG

Scan an IP address range for new servers that aren't being monitored, and run Smart Config for the new servers. The Discovery and Smart Config procedures can take some time, so an OK result means that the process has been started.

Required Parameters
START - Start of IP address range
END - End of IP address range

Example

https://server:81?API=DISCOVERY_CONFIG&KEY=msa8gbk4j78dbglaj&START=192.168.0.1&END=192.168.0.254

Output

:OK:

ADD_SERVER

Add and optionally configure the named server

Required Parameters
SERVER - name of the server that should be added. If the server already exists, it will be operated on (WIN, WMI and GROUP will not have an effect in that case).

Optional Parameters
WIN={0|1} - defaults to 0. Set to 1 if this is a Windows server.

WMI={0|1} - defaults to 0. Set to 1 if WMI polling should happen to collect System Details information for the server status report

CONFIG_PATH - defaults to none. Full path to a .cxml config file that specifies a configuration that should be applied to the new server. .cxml files are created by exporting a computer's configuration, or by using the EXPORT_SERVER API below. The file must be on the same computer as PA Server Monitor is running on.

GROUP - defaults to none (which implies the top level group). The full path to the group that the server should be placed in, for example: Servers/Devices^Seattle^Exchange Servers (where the ^ delimits group names).

Example

https://server:81?API=ADD_SERVER&KEY=msa8gbk4j78dbglaj&SERVER=MAILSRV2&WIN=1 &WMI=1&CONFIG_PATH=C:\Configs\Mail+Config.cxml

Output

:OK:

DELETE_SERVER

Delete the named server, along with all of its monitors

Required Parameters
CID - Computer ID for the computer to target for the operation. Computer IDs can be obtained via the GET_SERVER_LIST (XML output) above.
{deprecated} SERVER - name of the server that should be deleted

Example

https://server:81?API=DELETE_SERVER&KEY=msa8gbk4j78dbglaj&CID=125

Output

:OK:

EXPORT_SERVER

Exports the configuration of the specified server in a .cxml file. Per-server passwords (if any) are NOT exported.

Required Parameters
CID - Computer ID for the computer to target for the operation. Computer IDs can be obtained via the GET_SERVER_LIST (XML output) above.
- or -
SERVER - Name of the computer to target. If there are multiple computers with the same name (perhaps at different locations), which one is returned is not defined.

Optional Parameters
PATH - Full path to the output file. If this is not given, the file will be saved to C:\Program Files\PA Server Monitor\Config\Backup\Export_Computer_{CID}.cxml

Note: Be careful where these files are saved as some monitor configurations might contain sensitive information.

Example

https://server:81?API=EXPORT_SERVER&KEY=msa8gbk4j78dbglaj&CID=125

Output

:OK:

SET_SERVER_PROP

Sets a custom property on a server. If the property value is empty, the custom property is removed.

Required Parameters
CID - Computer ID for the computer to target for the operation. Computer IDs can be obtained via the GET_SERVER_LIST (XML output) above.
- or -
SERVER - Name of the computer to target. If there are multiple computers with the same name (perhaps at different locations), which one is returned is not defined.
PROPNAME - Name of the property to set
PROPVAL - Value of the property to set

Example

https://server:81?API=SET_SERVER_PROP&KEY=msa8gbk4j78dbglaj&CID=125
&PROPNAME=Customer&PROPVAL=IBM

Output

:OK:

GET_SERVER_PROP

Retrieves a custom property on a server. If the property is not defined, an empty value is returned.

Required Parameters
CID - Computer ID for the computer to target for the operation. Computer IDs can be obtained via the GET_SERVER_LIST (XML output) above.
- or -
SERVER - Name of the computer to target. If there are multiple computers with the same name (perhaps at different locations), which one is returned is not defined.
PROPNAME - Name of the property to retrieve

Example

https://server:81?API=GET_SERVER_PROP&KEY=msa8gbk4j78dbglaj&CID=125&PROPNAME=Customer

Output

:START:
IBM
:END:

ADD_GROUP

Add the given group if it doesn't already exist

Required Parameters
NAME - Full of the group name. For example, a group named "Exchange Servers" under the top "Servers\Devices" would set NAME to Servers\Devices^Exchange%20Servers (delimit groups with ^, URL encode, so a space becomes %20)

Example

https://server:81?API=ADD_GROUP&KEY=msa8gbk4j78dbglaj&NAME=Servers\Devices^New%20York^Web

Output

:OK:

DELETE_GROUP

Delete the named group. If it contains child groups or servers, they will become orphaned and moved to the top Servers\Devices group the next time the monitoring service is restarted.

Required Parameters
NAME - Full of the group name. For example, a group named "Exchange Servers" under the top "Servers\Devices" would set NAME to Servers\Devices^Exchange%20Servers (delimit groups with ^, URL encode, so a space becomes %20)

Example

https://server:81?API=DELETE_GROUP&KEY=msa8gbk4j78dbglaj&NAME=Servers\Devices^New%20York^Web

Output

:OK:

DO_BACKUP

Once a day and any time the monitoring service starts, the configuration is backed up to C:\Program Files\PA Server Monitor\Config\Backup. Using this API command, you can force the backup to happen on demand.

Example

https://server:81?API=DO_BACKUP&KEY=msa8gbk4j78dbglaj

Output
A new backup file is created in C:\Program Files\PA Server Monitor\Config\Backup

GOTO_SERVER_REPORT

Pass a server name and get forwarded to that server's status report

Required Parameters
CID - Computer ID for the computer to target for the operation. Computer IDs can be obtained via the GET_SERVER_LIST (XML output) above.
{deprecated} SERVER - name of the server

Example

https://server:81?API=GOTO_SERVER_REPORT&KEY=msa8gbk4j78dbglaj&CID=362

Output
Browser gets redirected to the given server's status report page

PA Server Monitor

Help Map