CopyScenario API

CopyScenario 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 CopyScenario API is used to automatically copy the LiveScenario, or specified scenario, and create a new What-if scenario in PlanetTogether. When a specified scenario does not exist within PlanetTogether, the function will create a new scenario from the LiveScenario if the CreateScenarioIfNew value is set to true.

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
  • CreateScenarioIfNew (boolean) - a true or false value indicating whether a new scenario should be created—upon scenario data input validation failure (e.g., No scenario exists with specified name or Id)
  • IsBlackBoxScenario(boolean) - a true or false value indicating whether a new scenario should be created and deleted once a series of simulations and data publishing is performed.
  • TimeoutMinutes (double) - how long to wait for the scenario to be copied successfully.

API Call

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

 CopyScenarioResponse resp = a_client.CopyScenario(copyRequest);

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 CopyScenarioRequest : ApsWebServiceScenarioRequest
{
[DataMember(IsRequired = false)]
public string ScenarioName { get; set; }

[DataMember(IsRequired = false)]
public bool CreateScenarioIfNew { get; set; }

[DataMember(IsRequired = false)]
public bool IsBlackBoxScenario { get; set; }

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

      API Request Example

      //Create a typed request
      CopyScenarioRequest copyRequest = new CopyScenarioRequest()
      {
      ScenarioName = a_scenarioName,
      CreateScenarioIfNew = a_createScenarioIfNew,
      IsBlackBoxScenario = false,
      TimeoutMinutes = 3
      };

      //Request Base
      copyRequest.UserName = a_username;
      copyRequest.Password = a_pwd;
      copyRequest.TimeoutDuration = TimeSpan.FromMinutes(1);

      //Scenario Request
      copyRequest.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;
      CopyScenarioResponse resp = a_client.CopyScenario(copyRequest);
      Console.WriteLine($"Response received after '{DateTime.Now.Subtract(start)}'");

      API Scenario Confirmation

      The API Scenario Confirmation holds the specific values related to a PlanetTogether scenario. The related API Response contains a reference to the scenario's property values using this Data Contract.

      • Data Contract
      [DataContract]
      public class ScenarioConfirmation
      {
      [DataMember(IsRequired = true)]
      public long ScenarioId { get; set; }

      [DataMember(IsRequired = true)]
      public string ScenarioName { get; set; }

      [DataMember(IsRequired = true)]
      public string ScenarioType { get; set; }

      internal void Validate()
      {
      if (ScenarioId == long.MinValue || string.IsNullOrEmpty(ScenarioName) || string.IsNullOrEmpty(ScenarioType))
      {
      throw new FaultException("Invalid scenario data.");
      }
      }
      }
      • Response Example
      //Sending a request
      a_start = DateTime.Now;
      CopyScenarioResponse resp = a_client.CopyScenario(copyRequest);

      //Display response scenario confirmation data
      if (resp.ResponseCode == EApsWebServicesResponseCodes.Success)
      {
      Console.WriteLine($"Success: Scenario '{resp.Confirmation.ScenarioName}' created under Id:{resp.Confirmation.ScenarioId} with Type:{resp.Confirmation.ScenarioType}");
      if (resp.Exception)
      {
      Console.WriteLine($"Errors: Invalid scenario data entered - {resp.ErrorMessage}");
      }
      }
      else
      {
      Console.Write("Scenario Copy not completed.");
      }

      Related APIs

      When a scenario name or Id is specified, the GetScenarios API is used to validate the input. When a specified scenario does not exist—and the CreateScenarioIfNew is true—the CopyScenario API will create a new scenario from the LiveScenario.