DeleteScenario API

DeleteScenario API Features

Examples in this guide reference code from the APS Web Service Client Sample project with a web service proxy configured. If you are just getting started with the APS Web Services APIs, please see our client sample.

API Function

The DeleteScenario API is used to delete the specified scenario from PlanetTogether. Validation is performed on the scenario data input before deleting the specified scenario. If the scenario does not exist within PlanetTogether, no action will be performed. 

API Validation

Both the scenario name and scenario Id are validated separately for matches to existing scenarios in PlanetTogether before selecting a scenario marked for deletion. 

The following validation rules apply when both scenario name & Id are submitted:

  • First, both are valid & match the same scenario - the specified scenario is deleted.
  • Both are valid & match different scenarios - the scenario matching the specified Id is deleted.

API Parameters

  • Username (string) - the user's username performing the call
  • Password (string) - the user's related password
  • TimeoutDuration (TimeSpan) - the time to wait when trying to connect to Extra Services or getting a data lock. If this parameter is not included in the request, a default value of 30 seconds will be used.
  • ScenarioId (long) - the scenario Id to which the import should apply
  • ScenarioName (string) - the name of the scenario to which the import should apply

API Call

Once the typed Request is created, the API call can be made using the following format:

 DeleteScenarioResponse resp = a_client.DeleteScenario(deleteScenarioRequest);

API Request

This API request inherits from ApsWebScenarioRequest. Check out our KB article on the API Request Base classes to learn more: Basic API Structure

To use the API, you must create a typed Request using the Request Data Contract. The related web client will use this Request to trigger the process.

  • Data Contract
[DataContract]
public class DeleteScenarioRequest : ApsWebScenarioRequest
{
[DataMember(IsRequired = false)]
public string ScenarioName { get; set; }

[DataMember(IsRequired = true)]
public double TimeoutMinutes { get; set; } = 5;
}

      API Request Example

      //Create a typed request
      DeleteScenarioRequest deleteScenarioRequest = new DeleteScenarioRequest()
      {
      ScenarioName = a_scenarioName,
      TimeoutMinutes = 3
      };

      deleteScenarioRequest.UserName = a_username;
      deleteScenarioRequest.Password = a_pwd;
      deleteScenarioRequest.ScenarioId = long.MinValue;

      API Response

      All API calls return a Response object to help determine the result of the call. Check out our Basic API Structure KB article for more information.

      Response Example

      //Sending a request
      a_start = DateTime.Now;
      DeleteScenarioResponse resp = a_client.DeleteScenario(deleteScenarioRequest);
      Console.WriteLine($"Response received after '{DateTime.Now.Subtract(start)}'");

      //Display response scenario confirmation data
      if (resp.ResponseCode == EApsWebServicesResponseCodes.Success)
      {
      Console.WriteLine($"Success: Scenario validated and deleted for '{resp.Confirmation.ScenarioName}' with Id '{resp.Confirmation.ScenarioId}'");

      if (resp.Exception)
      {
      Console.WriteLine($"Input Errors: {resp.ErrorMessage}");
      }
      }
      else
      {
      Console.Write("Scenario Delete not completed - ");

      if (resp.ResponseCode == EApsWebServicesResponseCodes.InvalidLiveScenario)
      {
      Console.WriteLine($"Attempting to delete Live Scenario - Id '{scenarioId}' received");
      }
      else if (resp.ResponseCode == EApsWebServicesResponseCodes.InvalidScenarioIdAndName)
      {
      Console.WriteLine($"No valid scenario data entered");
      }
      else
      {
      Console.WriteLine($"{resp.ErrorMessage}");
      }

      if (resp.Exception)
      {
      Console.WriteLine($"Input Errors: {resp.ErrorMessage}");
      }
      }

      API Response Base

      Reference the API Response section of the Import API article for details on the API Response Base.

      Related APIs

      The GetScenarios API is used to validate the input.