Getting Started #

Overview #

To run a simulation, follow these steps.

1. Select a client tool
2. Create a user account
3. Select a model to use
4. Execute a simulation
5. Track scenario progress
6. Receive scenario results

Step 1 - Select client tool #

To interact with Zypr's API, you will need to use the Swagger UI or select a command-line tool like cURL, or a client application tool such as Postman. The Swagger UI is front-end GUI to Zypr endpoints and provides the quickest way use them if you are not familiar with these other tools.

Step 2 - Create user account #

To create a user account you will use the Post endpoint in User Management define a user and request an activation code. The User request object looks like this:

Request object #

  { 
    "FirstName": "Sally",
    "LastName": "Doe",
    "Email": "sallydoe@company.com",
    "Organization": "my company name"
  }

If you are using Swagger UI, go to the "Register a new trial user" endpoint, click the "Try it out" button, complete the object with your user information, and click blue execute button. If you are using another tool, add this object to the request body as shown here.

You should receive a response object in the following form:

Response object #

  {
    "Message": "Email sent to sallydoe@company.com 
                that contains activation code."
  }

In the email you receive contains an activation code. To complete user registration, you will use the the PUT endpoint in User Management to enter your activation code, as shown below using Swagger UI.

After confirming your email address, you should receive a response object in the following form:

Response object #

  {
    "UserName": "sallydoe@company.com",
    "Role": "TrialUser",
    "ApiKey": "xxxxxxxxxxxxxxxxxxxxx",
    "ApiKeyExpiration": "date"
  } 

This object contains your API key. You will need this key to execute a simulation and invoke other API endpoints. If you are using Swagger UI, you need to click the Authorize button at top-right of the Swagger UI page and follow the directions for entering your API key.

Please keep your API key a secret. Do not save or post your API key in a publicly accessible area.

Step 3 - Select model to use #

Included in the email you received with your activation code are three attachments. Each attachment is a predefined PoolResourcesModel object. You may use them as a starting point to define your own pool model, or use them to execute simulations to familiarize yourself with Zypr.

Step 4 - Execute simulation #

To execute a simulation you will use the POST endpoint in Simulation Management. Add a completed PoolResourcesModel object to the request body. If you are using Swagger UI, it looks like this:

Your entry should have an object structure that looks like this:

{
  "PoolResourcesModel": {
    "Settings": {},
    "SimulationRules": {},
    "EvolutionRules": {},
    "ValuationRules": {},
    "NewServerConfiguration": {},
    "PowerConsumptionTerms": {},
    "FacilityConsumptionTerms": {},
    "SoftwareResource":{
        "SoftwareStackRegistry":[],
        "SoftwareInventoryTerms":[]
    },
    "ServerInventory":[],
    "JumpEvents":[],
    "Constraints":[]
  }
}

If your model passed validation (i.e., no errors), the response will be a Scenario object that looks like this:

  {
    "Id":"Your unique scenario id",
    "StatusNbr": 3,
    "StatusDescription": "Model validation succeeded",
    "SimulationStates": [
      {
        "StatusTimestamp" : "date-time stamp",
        "StatusNbr" : 1,
        "Message" : "Received request"
      },
      {
        "StatusTimestamp" : "date-time stamp",
        "StatusNbr" : 2,
        "Message" : "Start request initiated"
      },
      {
        "StatusTimestamp" : "date-time stamp",
        "StatusNbr" : 3,
        "Message" : "Model validation succeeded"
      }
    ],
    "Progress": null,
    "ResourcesForecast": [],
    "NoSolutionGraphs": [],
    "Errors": [],
    "Settings": {},
  }

This response object is not the final result, but it does contain the Scenario Id that Zypr created. You will need this id at the next step.

Although you received this Scenario response object, Zypr continues to execute the simulation and updates your unique scenario request record of its progress.

Step 5 - Track scenario progress #

Because a simulation may take several seconds to several minutes or longer to complete, you may track the progress of a running scenario using the GET endpoint in Simulation Management. Alternatively, you may elect not to track the progress of a running simulation and wait for the results to be emailed to you.

All three models included in your activation email have been set in the Settings object to send your scenario results to you by email.

Step 6 - Receive scenario results #

Receipt of a completed scenario can by accomplished by querying the status of your simulation using the scenario id, or waiting for the final results to be sent to you by email. If you forget the scenario id, you may use the GET endpoint in Simulation Management to retrieve recently executed scenarios and their ids.

All attempted simulations return a Scenario object with a unique scenario id. A scenario that completes with no errors will include a collection of resource forecasts contained in the ResourcesForecast object. A scenario that fails validation of the Pool Resources Model will return a Scenario object with an empty ResourcesForecast object and an Errors object that identifies the error.

A scenario that includes one or more constraints may return an empty ResourcesForecast object if a value in the Constraints object is too restrictive for any solution to be found. Alternatively, a solution may be found, and identified in the ResourcesForecast object, while simultaneously the NoSolutionsGraph object contains graphs whose solutions did not comply with the set constraints.