Edit Monitor (XML API)

Last modified on July 26, 2024

To update the monitor configuration, send a POST request to /devices/upload with an XML body containing the parameters you want to change. The monitor ID is specified by the ObjDevice element.

The typical flow is to log in, call List Monitors to get the monitor IDs, change some values, then call Edit Monitor to update the monitor configuration.

Notes:

  • The XML API lets you edit Web URL, API endpoint, email, FTP, TCP, DNS and ping monitors. To edit DéjàClick, SoapUI, and Selenium monitors, use the JSON API instead. BitBar monitors, security scans and ServerAgents cannot be edited via API.

  • Changing monitor locations is not supported in the XML API, but is supported in the JSON API.

Request URL

POST https://www.alertsite.com/restapi/devices/upload

Request body

XML

<Upload>
   <TxnHeader>
      <Request>
         <Login>_LOGIN_</Login>
         <SessionID>_SESSION_</SessionID>

         <TxnHeader>
            <ObjDevice>_MONITOR_ID_</ObjDevice>
            <TxnPlan>_PLAN_</TxnPlan>
            <TxnDetail
               Caching="n"
               DeviceType="w"
               Emailaddr="emailaddr.here"
               FullIP="111.222.333.444"
               FullpageTimeOut="20"
               HomeLocation="1"
               HttpFollowRedirect="y"
               HttpMethod="g"
               HttpVersion="1.1"
               Interval="5"
               IntervalFullpage="60"
               Keyword="abc"
               KeywordInvertMatch="n"
               KeywordType="PlainText"
               Monitor="y"
               MonitorLocations="0"
               MonitorType="I"
               Notify="y"
               NotifyContent="n"
               Password="roundtrip email password"
               PingError="n"
               POP3addr="pop3addr.here"
               Port="80"
               RealmPassword="basic auth password"
               RealmUserId="basic auth userid"
               Report302Errors="n"
               Report401Errors="n"
               ResolveDNS="y"
               RR2Enabled="n"
               SMTPaddr="smtpaddr.here"
               SSLCheckCertDate="n"
               TimeOut="30"
               TraceError="y"
               url="www.example.com"
               UserId="roundtrip email userid"
               />
            <TxnName>_MONITOR_NAME_</TxnName>

            <!-- Assertions for API endpoint monitors -->
            <AssertionList>
               <Assertion>
                  <Source>Response</Source>
                  <Comparison>does not contain</Comparison>
                  <Value>error</Value>
               </Assertion>
               <Assertion>
                  <Source>JSON Response</Source>
                  <Property>store.book[0].title</Property>
                  <Comparison>equals</Comparison>
                  <Value>The Lord of the Rings</Value>
               </Assertion>
            </AssertionList>

         </TxnHeader>
      </Request>
   </TxnHeader>
   <Source>REST_Client</Source>
</Upload>

Monitor data fields

The monitor to edit is specified by the <ObjDevice> tag. You can get monitor IDs by using the List Monitors operation.

In the example above, more monitor parameters have been given than are required in a minimal XML request. These extra parameters are presented here to illustrate instructions for expanded usage of the API.

The relevant XML tags of a monitor are described below. The rest can be excluded from the <TxnDetail> tag.

Note: Some parameters in <TxnDetail> apply only to specific monitor types. For example, POP3addr is only used by Email (POP) server monitors ( DeviceType = p). In other monitor types, this parameter should be left blank: <POP3addr></POP3addr> or <POP3addr/>.

TxnName

Required. The monitor name.

Note: XML API does not support quotes (") and backslashes (\) in monitor names.

DeviceType

Required. The monitor type.

Value Description
w Web site (http://)
s Secure web site (https://)
a API endpoint (http://)
b Secure API endpoint (https://)
f FTP server
F Secure FTP server
p Email (POP) server
e Email (SMTP) server
i Email (IMAP) server
r Roundtrip Email (POP/SMTP)
t TCP (Simple TCP Connect)
empty string Ping (Server/Device Ping)
n DNS (name server)

HomeLocation

In Add Monitor and Edit Monitor, HomeLocation must be 1.

Interval

The monitoring interval, in minutes. Possible values depend on the monitoring plan selected for the monitor.

Keyword, KeywordType and KeywordInvertMatch

Keyword matching options. Used for web URL and DNS monitors (monitor types w, s and n).

AssertionList

A list of assertions used to validate the response from the API call. Applies only to API endpoint monitors (monitor types a and b).

<AssertionList> contains one or more <Assertion> tags, and each <Assertion> contains the following:

Source

The source of the value verified by this assertion:

  • Response – entire response body.

  • JSON Response – a specific field in a JSON response.

  • XML Response – a node or attribute in an XML response.

  • Timeout – the maximum allowed response time, in seconds, up to three decimal places. For example, 0.25.

  • Status Code – the HTTP status code of the response. This status is compared against a comma-separated list of valid or invalid status codes.

  • Header – an HTTP response header, such as Content-Type.

Property

If Source=JSON Response, this is a JSONPath expression that specifies the JSON field being verified, such as store.book[0].title.

If Source=XML Response, this is an XPath expression that specifies the XML node or attribute being verified, such as //user[@id='12345']/name.

If Source=Response, Timeout or Status Code, this field is not used.

If Source=Header, this is the name (case-insensitive) of an HTTP response header, such as Content-Type.

Comparison

The comparison type to perform. Possible values:

  • Source=Response:
    • contains
    • does not contain
    • regular expression includes
    • regular expression excludes
  • Source=JSON Response or XML Response:
    • equals
    • count
    • exists
    • does not exist
    • regular expression includes
    • regular expression excludes
  • Source=Timeout:
    • less than or equal
  • Source=Status Code
    • equals
    • does not equal
  • Source=Header
    • equals
    • exists
    • regular expression includes

Value

The expected value for the assertion to pass. It can be a string or a regular expression. If Comparison=exists or does not exist, Value is an empty string.

When sending Value to AlertSite, if the value contains & or <, encode these characters as &amp; and &lt; respectively.

Monitor

Defines whether the monitoring is enabled. Possible values: y, n.

MonitorLocs

If rotated locations are enabled (RR2Enabled), this is the number of locations per interval. Otherwise 0.

MonitorType

The monitoring mode for this monitor.

Value Description
G Global Notify
I Primary
R Round Robin
U SLA (MultiPOP)
V Global Verify

Pop3addr

The POP3 address for a Email (POP) server monitor (DeviceType = p).

Port

If port number is not supplied, the default port number will be used for the specified service.

RealmUserId and RealmPassword

User name and password used when a web site requires Basic authentication.

ResolveDNS

To enable DNS to be resolved, this parameter should be set to y.

RR2Enabled

Defines whether to rotate locations. Possible values: y, n.

This parameter can be used with monitors that use MonitorType set to V (Global Verify) or R (Round Robin). If rotation is enabled, MonitorLocs specifies the number of locations per interval.

SMTPaddr

The SMTP address for an Email (SMTP) server monitor (DeviceType = e).

TimeOut

Monitor timeout, in seconds.

url

The URL to monitor.

UserID and Password

Username and password to access the mailbox, used for a round-trip email monitor (DeviceType = r).

Response body

On success, the operation returns Status 0:

XML

<Response>
   <Status>0</Status>
   <Message>No errors.</Message>
   <SessionID>1ae01751673e33eb</SessionID>
   <ObjDevice>48423</ObjDevice>
   <ObjCust>24567</ObjCust>
   <Custid>C24567</Custid>
   <Company>WidgetWorld</Company>
   <CurrPlan></CurrPlan>
   <CurrInterval></CurrInterval>
   <AvailablePlans>WTP5-1.5x:1:1</AvailablePlans>
   <TxnOut></TxnOut>
</Response>

See Also

Add Monitor
List Monitors
Get Monitor
Delete Monitor
Get Monitor Status
AlertSite XML API

Highlight search results