Rational Test Control Panel Scenarios REST API Reference

See the Rational Test Virtualization Server Reference Guide for more information on scenarios on Rational Test Control Panel.

Forward compatibility

Query URL

• URL:
  • <RTCP_BASE_URL>/rest/scenarios/

GET request

• Query parameters:
  • domain (Required): The name of the domain.
  • env (Required): The name of the environment.
  • scenarioName (Optional): The name of the scenario.
  • scenarioId (Optional): The ID of the scenario.
  • owner (Optional): The name of the user who owns the scenario.
• Examples:
  • <RTCP_BASE_URL>/rest/scenarios/?domain=default&env=testEnv&owner=jbloggs&scenarioId=51624366-256c-426c-a9c4-e17d8c904490
  • <RTCP_BASE_URL>/rest/scenarios/?scenarioName=Steve%27s%20scenario
• Response data:

  <scenarios>
      <scenario id="id" name="name" href="relative URL" />
      <scenario id="id" name="name" href="relative URL" />
      ...
  </scenarios>

  • href URLs point to scenarios.
• Response codes:
  • 200 OK (But may return an empty list).
  • 400 BAD REQUEST: If any required query parameters were missing, or if any parameters were invalid.
  • 412 PRECONDITION FAILED: If the domain or environment could not be found.

  If the response code is 400 or greater, and the Content-Type is text/plain, then the response body contains a plain-text error message.

Resources

Scenario

• URL:
  • Resolve the relative URL retrieved from the query URL response, relative to <RTCP_BASE_URL>/rest/scenarios/, as defined by section 5.2.2 of RFC 3986.
  • Normally this is in the form of <RTCP_BASE_URL>/rest/scenarios/[relative URL from query response], but this should not be relied upon.

GET request

• Response data:

  <scenario id="" name="" owner="owner username" status="RUNNING|STOPPING|STARTING|STOPPED">
      <stubs>
          <stub id="UUID" name="name" version="1.1" href="relative URL">
               <configuration>
                  <tags>
                       <tag name="my tag 1" value="default value" />
                       <tag name="my tag 2" value="" /> <!-- Default to empty string -->
                       <tag name="my tag 3" /> <!-- Default to null -->
                       ...
                  </tags>
                  <behaviours>
                       <behaviour name="behaviour instance name">
                           <parameters>
                               <parameter name="parameter name" value="default value" />
                               ...
                           </parameters>
                      </behaviour>
                      ...
                 </behaviours>
                 <logging level="DEFAULT|NONE|NORMAL|DEBUG" />
                 <response-time distribution="FIXED|UNIFORM|GAUSSIAN" minimum="0" maximum="1000" />
              </configuration>
              <agents>
                  <agent host="host name or IP (as specified by agent)">
                     <attributes>
                          <attribute value="attribute name" />
                          ...
                     </attributes>
                  </agent>
             </agents>
          </stub>
          ...
      </stubs>
  </scenario>

  • To determine if a scenario is currently running, check the status attribute.
  • The values all attributes (except value where appropriate) should be checked in a case-insensitive manner.
  • See the Rational Test Control Panel Stubs REST API Reference for information about the other elements.
• Response codes:
  • 404 NOT FOUND: If the scenario could not be found.
  • 412 PRECONDITION FAILED: If the domain or environment could not be found.

  If the response code is 400 or greater, and the Content-Type is text/plain, then the response body contains a plain-text error message.

POST on scenario - start scenario

• Request headers:
  • X-User: may be used to specify the user who is starting the scenario.
    • This will allow the operation to be performed through an already-obtained environment lock.
    • For more information about environment locks, see the Rational Test Virtualization Server Reference Guide and the Rational Test Control Panel Environment Locking REST API Reference.
  • Content-Type: application/xml
• Request data:

  <start-scenario>
      <settings>
          <before>
               <stop-stubs option="all|operations" />
          </before>
      </settings>
  </start-scenario>

  To start the scenario with default settings, just send:

  <start-scenario />

• Response codes:
  • 202 ACCEPTED (scenario will start in the background).
  • 400 BAD REQUEST: If the request data could not be understood.
  • 404 NOT FOUND: If the scenario could not be found.
  • 409 CONFLICT: If a scenario is already running.
  • 412 PRECONDITION FAILED: If the domain or environment could not be found.
  • 417 EXPECTATION FAILED: If there are no agents available to run the scenario.

  If the response code is 400 or greater, and the Content-Type is text/plain, then the response body contains a plain-text error message.

Scenario instance (Running scenario)

There is only ever at most one instance of a scenario at any given time.

• URL:
  • Append instance to the end of the scenario resource URL
    • e.g. <RTCP_BASE_URL>/rest/scenarios/[relative URL from query response]/instance

DELETE on scenario instance - stop scenario

• Request headers:
  • X-User: may be used to specify the user who is starting the scenario.
    • This will allow the operation to be performed through an already-obtained environment lock.
    • For more information about environment locks, see the Rational Test Virtualization Server Reference Guide and the Rational Test Control Panel Stubs REST API Reference.
• Response codes:
  • 202 ACCEPTED: The scenario will stop in the background.
  • 404 NOT FOUND: If the scenario could not be found.
  • 412 PRECONDITION FAILED: If the domain or environment could not be found.

  If the response code is 400 or greater, and the Content-Type is text/plain, then the response body contains a plain-text error message.