Skip to content

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

json
  { 
    "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.

register  

You should receive a response object in the following form:

Response object

json
  {
    "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.

confirm  

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

Response object

json
  {
    "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.

authorize  

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:

create scenario  

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

json
{
  "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:

json
  {
    "Id":"Your unique scenario id",
    "StatusNbr": 3,
    "StatusDescription": "Model validation succeeded",
    "JobStates": [
      {
        "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.

Ravello Analytics, LLC