Write Functionality in the Eggplant Monitoring API

You can make changes to the monitoring and alerting states of your monitors using the Eggplant Monitoring API. This strategy can be useful if you use continuous deployment mechanisms and want to programmatically control your monitors as part of your release cycle.

For users that already make such changes manually via the Eggplant Monitoring Portal Settings page, the API functions consistently in that you can change the monitoring status of user journeys as well as the monitoring and alerting status of your page monitors, steps of user journeys, or web service monitors. You can also force the settings for all steps of a user journey or web service with one call.

note

If you have Scheduled Timings set up for your monitors, these will operate independently of any changes you make via the API. If you are unsure if you have any set up, contact Eggplant customer support.

Important

Carefully construct any application or script that works with the API to ensure that your monitors remain configured as expected. If your application fails to re-enable monitoring, for instance, then you might be running with no monitoring or alerting and not be aware of this.

Each call to make a change is accounted for as a single request, and is aggregated along with any read requests your company makes each month. Note that you are limited to one update request per monitor every 5 seconds.

Authenticating

In order to make changes via the API, your company and user account needs to have been granted access as a user of the API service. This is the same as for users that need to read from the API. In addition, your user must be configured as an Account Administrator to make changes to monitor settings.

If you want to make changes via the API, you need to enable updating when you authenticate. Note that you can only do this if you are authorized.

You can either authenticate directly via the URL, or via the API login page, in the same way that you do with the traditional read API. Applications or programs must authenticate via a POST request either directly or via the login page while testing.

You must authenticate with an additional parameter:

POST request	Enable=UPDATE

The POST request to authenticate via the URL, with write capabilities included, looks like the following example:

POST request	username=email@address.co.uk password=password Enable=UPDATE

To authenticate via the API login page, select the Allow updates checkbox:

After authentication, you will be issued an API key with the appropriate permissions to make changes to your monitors. Note that even if you are an Account Administrator, you must follow this authentication process to get the necessary permissions to make changes.

You might need to log out to release your read-only key, by calling the Logout command:

GET request	/APIkey/Logout

Changing Monitor Settings

You can make a change to a only single monitor—user journey, web service, page, or step—at a time. You also can force a change to all the steps of a user journey or web service monitor; in that case, you still specify only one monitor to change (the parent user journey or web service monitor).

If you try to specify multiple monitors when making an update, you will get an error. This process ensures that when you make a change via the API, you can deal with the response and clearly determine if the change was successfully made or not.

Each of the monitor updates documented in the following sections is made by passing additional key/value pairs to the main URL, which is made up of the host/domain of the API, your API key, and the /Update path. In addition, you must specify the AccountId and Id of the monitor being changed.

Monitor updates:

• Page or Step of a User Journey or Web Service
• User Journey or Web Service
• Global Change for User Journey or Web Service Monitors

Page or Step of a User Journey or Web Service Monitor

It is possible to change both the monitoring and alerting status for page monitors, as well as for the steps of a user journey or web service monitor. You can't change the monitoring status alone—you must also define if alerting should be enabled or not.

Change the status by submitting values for the Monitoring and Alerting keywords, where values can be TRUE or FALSE (note that 1 and 0 can be used interchangeably to specify TRUE and FALSE, respectively).

The following list shows the different calls that can be made to configure the various states for these types of monitor:

• Enable monitoring and alerting: /Monitoring/TRUE/Alerting/TRUE
• Enable monitoring but disable alerting: /Monitoring/TRUE/Alerting/FALSE
• Disable monitoring and alerting: /Monitoring/FALSE/Alerting/FALSE

note

If you attempt to change the monitoring status only (i.e., by only specifying /Monitoring/TRUE), you will get an error, as you must also define the alerting status. This is only necessary for pages, or steps of a user journey/web service monitor.

As an example, if you have an update API key of 111222333444555666777888999000AB and want to enable monitoring and disabling alerting for page monitor MN1PG456 in account MN1A123, you construct requests as follows:

GET request	/111222333444555666777888999000AB/Update/AccountId/MN1A123/Id/ MN1PG456/Monitoring/TRUE/Alerting/FALSE
POST request	URL: /111222333444555666777888999000AB/Update AccountId=MN1A123 Id=MN1PG456 Monitoring=TRUE Monitoring=TRUE

User Journey or Web Service

When configuring a user journey or web service, you define if monitoring should be enabled or not. Note that the alerting status is defined at the step level. If you want to specifically change the monitoring or alerting status for all steps, you can force the changes as detailed in the section below.

Change the status by submitting values for the Monitoring keyword. Values can be TRUE or FALSE. The following list shows the different calls that can be made to configure the states for these types of monitors:

• Enable monitoring: /Monitoring/TRUE
• Disable monitoring: /Monitoring/FALSE

note

If you also attempt to change the alerting status (i.e., by specifying /Alerting/TRUE), you will get an error, as you cannot change alerting for user journey or web service monitors. If you want to force alerting status for all steps, see Global Change for User Journey or Web Service Monitors.

As an example, if you have an update API key of 111222333444555666777888999000AB and want to enable monitoring for user journey MN1UJ789 in account MN1A123, you construct requests as follows:

GET request	/111222333444555666777888999000AB/Update/AccountId/MN1A123/Id/ MN1UJ789/Monitoring/TRUE
POST request	URL: /111222333444555666777888999000AB/Update AccountId=MN1A123 Id=MN1UJ789 Monitoring=TRUE

Global Change for User Journey or Web Service Monitors

It is possible to change a user journey (or web service) monitor, as well as all of its steps. This is functionally the same as making such a change in the Portal Settings page (where it will also warn you and force the change to all steps).

As detailed above, the /Monitoring/ key is used to enable or disable the monitoring status of a user journey or web service. You can also include the /IncludeSteps/ key to indicate that all steps of the user journey or web service should be set to the same monitoring status you are setting.

The important addition is that if you change the monitoring status of a step in this way (globally for the whole user journey or web service), you must also define the alerting status for them (as consistent with the approach documented above). This is done by using specifying the /StepsAlerting/ key.

As with all the other parameters documented, the value is set to either TRUE or FALSE. The following list describes the different calls that can be made to configure the various states for these types of monitor:

• Enable monitoring and alerting for a user journey and all of its steps: /Monitoring/TRUE/IncludeSteps/TRUE/StepsAlerting/TRUE
• Enable monitoring for a user journey whilst disabling alerting for all of its steps: /Monitoring/TRUE/IncludeSteps/TRUE/StepsAlerting/FALSE
• Disable monitoring and alerting for a user journey and all of its steps: /Monitoring/FALSE/IncludeSteps/TRUE/StepsAlerting/FALSE

You must specify both a monitoring and an alerting status for a step, so if you specify IncludeSteps/FALSE, any StepsAlerting value you enter will be ignored.

As an example, if you have an update API key of 111222333444555666777888999000AB and want to enable monitoring for user journey MN1UJ789 in account MN1A123, as well as enabling monitoring and disabling alerting for all associated steps, you construct requests as follows:

GET request	/111222333444555666777888999000AB/Update/AccountId/MN1A123/Id/ MN1UJ789/Monitoring/TRUE/IncludeSteps/TRUE/StepsAlerting/FALSE
POST request	URL: /111222333444555666777888999000AB/Update AccountId=MN1A123 Id=MN1UJ789 Monitoring=TRUE IncludeSteps=TRUE StepsAlerting=FALSE

Query Responses

Each query made results in a response that clearly defines whether or not the change was successfully made. Note that changing a value to be the same as the current value is permitted—that is, the query response will show a successful change.

In addition, you can use the traditional read API to check the value of specific settings if needed. This is particularly useful if you are writing an interface to check the status of the monitor before making a change (e.g., disabling the monitor) so that the original state can be reset later on.

The main item to look for in the response is that the Status should be "Ok" if the change was successfully made:

-<SiteConfidenceApi Version="current">
  <Request/>
  <Response Status="Ok" Code="200" Message="Success."/>
</SiteConfidenceApi>

It is important that any application or script you write to interface with the API checks that updates were successful before proceeding.

Check Status

It is possible to check the monitoring status and alerting status using a standard API query.

For example, to check these for page MN1PG456 in account MN1A123 using an API key of 111222333444555666777888999000AB, you construct a request as follows:

GET Request	/111222333444555666777888999000AB/Return/[Account[Pages[Page[Monitoring,Alerting]]]]/AccountId/ MN1A123/Id/MN1PG456/

We can see the status for both monitoring and alerting for this page in the response:

-<SiteConfidenceApi Version="Current">
  <Request Return="[Account[Pages[Page[Monitoring,Alerting]]]]" AccountId="MN1A123" Id="MN1PG456"/>
  -<Response Status="Ok" Code="200" Message="Success.">
    -<Account>
      -<Pages>
        <Page Monitoring="false" Alerting="false"/>
      </Pages>
    </Account>
  </Response>
</SiteConfidenceApi>

In this next example, we can check the monitoring status for user journey MN1UJ789 in account MN1A123 using an API key of 111222333444555666777888999000AB:

GET request	/111222333444555666777888999000AB/Return/[Account[UserJourneys[UserJourney[Monitoring]]]]/ AccountId/MN1A5/Id/MN1UJ789/

We can see the monitoring status for this user journey in the response:

-<SiteConfidenceApi Version="Current">
  <Request Return="[Account[UserJourneys[UserJourney[Monitoring]]]]" AccountId="MN1A123" Id="MN1UJ789"/>
  -<Response Status="Ok" Code="200" Message="Success.">
    -<Account>
      -<UserJourneys>
        <UserJourney Monitoring="true"/>
      </UserJourneys>
    </Account>
  </Response>
</SiteConfidenceApi>

In this last example, we can query for the monitoring status for a user journey, as well as the monitoring and alerting status of each step, giving us a complete picture of the current settings for this monitor.

For user journey MN1UJ789, which contains the two steps MN1S162 and MN1S163, we construct a request as follows:

GET request	/111222333444555666777888999000AB/Return/[Account[UserJourneys[UserJourney[Monitoring,Steps[Step [Monitoring,Alerting]]]]]]/AccountId/MN1A123/Id/MN1UJ789,MN1S162,MN1S163/

This returns the following response:

-<SiteConfidenceApi Version="Current">
  <Request Return="[Account[UserJourneys[UserJourney[Monitoring,Alerting]]]]" AccountId="MN1A123" Id="MN1UJ789,MN1S162 ,MN1S163"/>
  -<Response Status="Ok" Code="200" Message="Success.">
    -<Account>
      -<UserJourneys>
        -<UserJourney>
          -<Steps>
            <Step Monitoring="true" Alerting="false"/>
            <Step Monitoring="true" Alerting="false"/>
          </Steps>
        </UserJourney>
      </UserJourneys>
    </Account>
  </Response>
</SiteConfidenceApi>

Errors, Warnings, and Failures

If an update query fails, you will get an overall Status of Fail along with any further information given as an error code. For example, if you attempt to update a page monitor by enabling the alerting status while disabling the monitoring status, which is an invalid configuration, you get the following response:

-<SiteConfidenceApi Version="Current">
  <Request/>
  -<Response Status="Fail" Code="711" Message="Invalid update request"/>
    -<Errors>
      <Error Code="706" Message="[ AccountID: MN1A5, UID: MN1PG178 ] - You cannot enable alerting if disabling monitoring">
    </Errors>
  </Response>
</SiteConfidenceApi>

We can see that there was a failure because the update included an invalid update request. In addition, there is a nested Error Code element in Errors that provides more information as to why the request was invalid.

It is important that any application or script you write to interface with the API checks that updates were successful before proceeding. The following table lists the details of the various error codes:

Error Code	Description
700	You tried to update multiple monitors in one query (this is not permitted)
701	You specified more than one account ID whilst updating (this is not permitted)
702	You attempted to update a monitor type that is not supported
703	You attempted to update a parameter that is not supported for the type of monitor chosen
704	No value was given against the parameter (TRUE or FALSE)
705	No value was given against the parameter (TRUE or FALSE)
706	Specify the Monitoring and Alerting status for this kind of monitor
707	The monitor you are trying to change is invalid
708	You are attempting to update a monitor with a read-only API key
709	No account ID has been specified
710	No monitor ID has been specified
711	The update request is invalid
712	You have attempted to update a monitor setting too soon after you last changed it. Wait 5 seconds and try again.
713	Internal error
714	Invalid parameter
715	The monitor you are trying to change does not exist
716	The account you are trying to change does not exist

In addition, warning conditions can occur, which are detailed below:

Warning Code	Description
1100	You have attempted to authenticate with the API and requested to enable updates, but you are not an account administrator. You have been granted a read-only API key.