Import/Refresh Data API

Import 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 Import API is used to automatically import data into PlanetTogether into the LiveScenario, or specified scenario. When a specified scenario does not exist within PlanetTogether, the function has the capability to create it if the CreateScenarioIfNew value is set to true.

API Parameters

The Import API uses the following 6 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.
  • ScenarioName (string) - the name of the scenario to which the import should apply
  • ScenarioId (long) - the scenario Id 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)

API Call

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

//Sending a request
ApsWebServiceResponseBase resp = client.Import(importRequest);

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 for reference. This is not needed on the client.
[DataContract]
public class ImportRequest : ApsWebScenarioRequest
{
[DataMember(IsRequired = false)]
public string ScenarioName { get; set; }

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

Request Example

//Create a Import request
APSWebServiceRef.ImportRequest importRequest = new ImportRequest() {
ScenarioName = scenarioName,
CreateScenarioIfNew = createScenarioIfNew
};

//Request Base
importRequest.UserName = username;
importRequest.Password = pwd;
importRequest.TimeoutDuration = TimeSpan.FromMinutes(1);

//Scenario Request
importRequest.ScenarioId = long.MinValue;

Omitting the TimeoutDuration or using a zero value will cause the server to return a SuccessWithoutValidation result and not wait for the import to complete. If sequential actions are triggered after the Import, make sure to set a time out long enough for the import process to complete.

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
start = DateTime.Now;
ApsWebServiceResponseBase resp = client.Import(importRequest);
Console.WriteLine($"Response received after '{DateTime.Now.Subtract(start)}'");

//Display results
if (!a_response.Exception)
{
Trace($"Completed with Zero Errors");
}
else
{
Trace($"Completed with Errors");
Trace(a_response.FullExceptionText);
}

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 CopyScenarios API creates a new scenario from the LiveScenario.