Update a browser test (UpdateTests, UpdateTestParameters, TestStatusUpdate)

You have created one or more tests and has deployed them successfully on sites in the Dynatrace Portal. Now you want to modify one or more of the test parameters for a test. For example, you want to change the frequency in minutes that the test is executed. The Test Management API provides three different tools for updating a monitor. It is extremely important for you to consider what these three tools have to offer and when it is appropriate to use each one.

The first tool is a web service method called UpdateTests(). This method assumes that the Dynatrace Synthetic Monitoring system is the most accurate source of information for the entire test provisioning data.

  • First query the system using the GetTests() method to get a complete snapshot of all the provisioning data for the test to be updated (a Monitor element).

  • Next, modify the fields requiring modification and resubmit the modified Monitor element as input to the UpdateTests() method.

The following is the workflow to use the Update tests method to perform an update:

Use the GetTests method to request a snapshot of the browser test to update. The following is a sample request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:prov="http://www.gomeznetworks.com/schemas/provisioning">
   <soapenv:Header/>
   <soapenv:Body>
      <prov:GetTestsRequest>
         <prov:Credentials>
            <prov:UserName>MyUser</prov:UserName>
            <prov:Password>MyPassword</prov:Password>
         </prov:Credentials>
	<prov:MonitorFilter>
		<prov:MonitorId>263756</prov:MonitorId>
	</prov:MonitorFilter>
      </prov:GetTestsRequest>
   </soapenv:Body>
</soapenv:Envelope>

The following is the response to the sample request:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
      <GetTestsResponse xmlns="http://www.gomeznetworks.com/schemas/provisioning">
         <ResponseStatus>SUCCESS</ResponseStatus>
         <Monitors>
            <Monitor name="Site Management Test SingleStepMonitor"
                     folder="Site Management Tests"
                     agentType="IE"
                     summaryFlag="On"
                     includeRenderTimeFlag="On"
                     frequencyInMins="60"
                     expirationDate="2012-08-15T10:17:12"
                     ipVersion="IPv4_only"
                     monitorStatus="Inactive"
                     folderStatus="Active"
                     monitorId="263756"
                     createDate="2012-07-19T14:17:11.953"
                     modifyDate="2012-08-14T20:13:03.693"
                     scriptId="263756">
               <MonitorSites>
                  <MonitorSite siteId="886"/>
                  <MonitorSite siteId="873"/>
                  <MonitorSite siteId="865"/>
                  <MonitorSite siteId="866"/>
                  <MonitorSite siteId="880"/>
               </MonitorSites>
               <Steps>
                  <Step stepSeqNum="0">
                     <URL>http://www.dynatrace.com</URL>
                     <DisplayName/>
                  </Step>
               </Steps>
            </Monitor>
         </Monitors>
      </GetTestsResponse>
   </soap:Body>
</soap:Envelope>

Make the changes to the Monitor element in the response and include it in your UpdateTests request. In this example, the frequency is changed from 60 minutes to 30 minutes.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:prov="http://www.gomeznetworks.com/schemas/provisioning">
   <soapenv:Header/>
   <soapenv:Body>
      <prov:UpdateTestsRequest>
         <prov:Credentials>
            <prov:UserName>MyUser</prov:UserName>
            <prov:Password>MyPassword</prov:Password>
         </prov:Credentials>
         <prov:Monitors>
            <prov:Monitor name="Site Management Test SingleStepMonitor - Updated"
                          folder="Site Management Tests"
                          agentType="IE"
                          summaryFlag="On"
                          includeRenderTimeFlag="On"
                          frequencyInMins="30"
                          expirationDate="2012-08-15T10:17:12"
                          ipVersion="IPv4_only"
                          monitorStatus="Inactive"
                          folderStatus="Active"
                          monitorId="263756"
                          createDate="2012-07-19T14:17:11.953"
                          modifyDate="2012-07-21T00:05:00.583"
                          scriptId="263756">
               <prov:MonitorSites>
                  <prov:MonitorSite siteId="865"/>
                  <prov:MonitorSite siteId="866"/>
                  <prov:MonitorSite siteId="873"/>
                  <prov:MonitorSite siteId="880"/>
                  <prov:MonitorSite siteId="886"/>
               </prov:MonitorSites>
               <prov:Steps>
                  <prov:Step stepSeqNum="0">
                     <prov:URL>http://www.dynatrace.com</prov:URL>
                     <prov:DisplayName/>
                  </prov:Step>
               </prov:Steps>
            </prov:Monitor>

The following is the response to the sample request:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
      <UpdateTestsResponse
         xmlns="http://www.gomeznetworks.com/schemas/provisioning">
         <ResponseStatus>SUCCESS</ResponseStatus>
         <MonitorOrderResponses>
            <MonitorOrderResponse name="Site
              Management Test SingleStepMonitor - Updated"
                                  folder="Site Management Tests"
                                  monitorId="263756"
                                  monitorStatus="Inactive"
                                  orderStatus="SUCCESS">
               <Message>Successfully provisioned monitor:
                        AccountName = My Account Name,
                        MonitorName = Site Management Test SingleStepMonitor - Updated,
                        MonitorId =263756</Message>
            </MonitorOrderResponse>
         </MonitorOrderResponses>
      </UpdateTestsResponse>
   </soap:Body>
</soap:Envelope>

The advantage of the UpdateTests() method is that it can enforce the business rules governing a browser test on updates using some of the same code paths as those used to provision the test in the first place. If there are dependencies among test parameters within a test update, those dependencies are respected. For example, if you modify the ipVersionPreference on the test, the rules for the new ipVersionPreference will be correctly enforced on the site collection contained in the Monitor object. Also, you are able to predict the state of the browser test based solely on the UpdateTest() request, you do not have to refer to the request that created the monitor in the first place.

The disadvantage of the UpdateTests() method is that it works best when the test definitions are retrieved from the system before performing the update. However, if you are storing the test provisioning data outside the system, you may not want to retrieve a snapshot of the test from the system first. It is possible that you may only want to update a single property for the test, so you may not want to pass a complete Monitor definition to only change the test frequency or the list of sites where the Monitor is deployed.

If you do not want to use the UpdateTests() method, you can use another method called UpdateTestParameters(). This method allows you to pass a monitor id and all or any of the following:

  • A collection of MonitorProperty elements

  • A collection of Sites elements

  • A collection of Step elements

However many MonitorProperty elements that are passed are used to update the effected fields on the browser test. To only update the test frequency, for example, do not pass anything else. If you just want to perform site management on the browser test, do not pass the Monitor properties or Steps. To change only the display name on a Step, pass only the Step definition in the request with the modified display name.

The following is a sample request that updates a single property for a test:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:prov="http://www.gomeznetworks.com/schemas/provisioning">
   <soapenv:Header/>
   <soapenv:Body>
      <prov:UpdateTestParametersRequest>
         <prov:Credentials>
            <prov:UserName>MyUser</prov:UserName>
            <prov:Password>MyPassword</prov:Password>
         </prov:Credentials>
         <prov:PartialUpdate monitorId="263014">
            <prov:MonitorProperties>
               <prov:MonitorProperty name="IncludeRenderTime"
                                     value="On"/>
            </prov:MonitorProperties>
         </prov:PartialUpdate>
      </prov:UpdateTestParametersRequest>
   </soapenv:Body>
</soapenv:Envelope>

The following is a message that updates the list of sites to which an existing test is deployed:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:prov="http://www.gomeznetworks.com/schemas/provisioning">
   <soapenv:Header/>
   <soapenv:Body>
      <prov:UpdateTestParametersRequest>
         <prov:Credentials>
            <prov:UserName>MyUser</prov:UserName>
            <prov:Password>MyPassword</prov:Password>
         </prov:Credentials>
         <!--1 or more repetitions:-->
         <prov:PartialUpdate monitorId="270276">
            <prov:MonitorSites>
               <prov:MonitorSite siteId="777"
                                 siteName="TPNTS7 - MA: Boston"
                                 city="Lexington"
                                 state="MA"
                                 countryCode="US"
                                 ipV6Enabled="false"/>
               <prov:MonitorSite siteId="865"
                                 siteName="TPNPEKSA12 - Beijing China test"
                                 city="Beijing"
                                 state=""
                                 countryCode="CN"
                                 ipV6Enabled="false"/>
               <prov:MonitorSite siteId="866"
                                 siteName="TPNPEKSA02 - Beijing China test"
                                 city="Beijing"
                                 state=""
                                 countryCode="CN"
                                 ipV6Enabled="false"/>
               <prov:MonitorSite siteId="867"
                                 siteName="TPNTS18 - Boston, MA - Savvis"
                                 city="Waltham"
                                 state="MA"
                                 countryCode="US"
                                 ipV6Enabled="false"/>
               <prov:MonitorSite siteId="868"
                                 siteName="TPNTS17 - Boston, MA - Savvis"
                                 city="Waltham"
                                 state="MA"
                                 countryCode="US"
                                 ipV6Enabled="false"/>
               <prov:MonitorSite siteId="872"
                                 siteName="TPNTS16BA01 - Boston, MA - Savvis"
                                 city="Boston"
                                 state="MA"
                                 countryCode="US"
                                 ipV6Enabled="false"/>
               <prov:MonitorSite siteId="873"
                                 siteName="G7 Test Private Agent (NEW)"
                                 city="Boston"
                                 state="MA"
                                 countryCode="US"
                                 ipV6Enabled="false"/>
               <prov:MonitorSite siteId="880"
                                 siteName="TPNTS13 - Boston, MA - Savvis"
                                 city="Boston"
                                 state="MA"
                                 countryCode="US"
                                 ipV6Enabled="false"/>
               <prov:MonitorSite siteId="881"
                                 siteName="TPNTS12 - Boston, MA - Savvis"
                                 city="Boston"
                                 state="MA"
                                 countryCode="US"
                                 ipV6Enabled="true"/>
               <prov:MonitorSite siteId="884"
                                 siteName="TPNTS10 - Boston, MA - Savvis"
                                 city="Boston"
                                 state="MA"
                                 countryCode="US"
                                 ipV6Enabled="false"/>
               <prov:MonitorSite siteId="885"
                                 siteName="TPNTS9 - Boston, MA - Savvis"
                                 city="Boston"
                                 state="MA"
                                 countryCode="US"
                                 ipV6Enabled="false"/>
               <prov:MonitorSite siteId="886"
                                 siteName="TPNTS8 - Boston, MA - Savvis"
                                 city="Boston"
                                 state="MA"
                                 countryCode="US"
                                 ipV6Enabled="false"/>
               <prov:MonitorSite siteId="887"
                                 siteName="TPNTS11 - Boston, MA - Savvis"
                                 city="Boston"
                                 state="MA"
                                 countryCode="US"
                                 ipV6Enabled="true"/>
            </prov:MonitorSites>
         </prov:PartialUpdate>
      </prov:UpdateTestParametersRequest>
   </soapenv:Body>
</soapenv:Envelope>

The following is an example of a message that changes the display name of a step within a currently deployed test:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:prov="http://www.gomeznetworks.com/schemas/provisioning">
   <soapenv:Header/>
   <soapenv:Body>
      <prov:UpdateTestParametersRequest>
         <prov:Credentials>
            <prov:UserName>MyUser</prov:UserName>
            <prov:Password>MyPassword</prov:Password>
         </prov:Credentials>
         <prov:PartialUpdate monitorId="264019">
            <prov:Steps>
               <prov:Step stepSeqNum="0">
                  <prov:DisplayName>Acme Bank of Folstoff</prov:DisplayName>
               </prov:Step>
            </prov:Steps>
         </prov:PartialUpdate>
      </prov:UpdateTestParametersRequest>
   </soapenv:Body>
</soapenv:Envelope>

With the UpdateTests() method and with the UpdateTestParameters() method, you can also perform status updates on browser tests (activating or deactivating tests). If this is the only thing you want to do, you can use UpdateTestParameters(), which does only status updates, including test deletions.

The following is a message that deactivates an existing test:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:prov="http://www.gomeznetworks.com/schemas/provisioning">
   <soapenv:Header/>
   <soapenv:Body>
      <prov:TestStatusUpdateRequest>
         <prov:Credentials>
            <prov:UserName>MyUser</prov:UserName>
            <prov:Password>MyPassword</prov:Password>
         </prov:Credentials>
         <!--1 or more repetitions:-->
         <prov:TestStatusUpdate monitorId="270276" status="Inactive"/>
      </prov:TestStatusUpdateRequest>
   </soapenv:Body>
</soapenv:Envelope>