Skip to content
On this page

Pool Resources Model Object Reference

 

This PoolResourcesModel request object describes resources, demand, events, costs, rules, and constraints that govern future pool resource states, quantities, and license positions over time.

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

Attributes

Settings - object - required
This object sets properties for scenario handling.
SimulationRules - object - required
This object sets the objective function of the simulation.
EvolutionRules - object - required
This object sets rules for how pool resources evolve over time.
ValuationRules - object - required
This object defines financial parameters for how resources are valued.
PowerConsumptionTerms - object - required
This object defines the cost terms for electricity consumption.
FacilityConsumptionTerms - object - required
This object defines the cost terms for facility space consumption.
NewServerConfiguration - object - required
This object defines the configuration of a new server inventory that will be added to the pool.
SoftwareResource - object - required
Is the parent object for SoftwareStackRegistry and SoftwareInventoryTerms objects.
SoftwareStackRegistry - array of integers - required
This array contains license ids that define the initial software stack of the pool. The license ids correspond to license terms defined in SoftwareInventoryTerms object.
SoftwareInventoryTerms - array of objects - required
This array contains objects that describe relevant license terms.
ServerInventory - array of objects - required
This array contains objects that describe initial server inventory of the pool.
JumpEvents - array of objects - optional
This array contains objects that describe discrete events to influence the evolution and mix of pool resources.
Constraints - array of objects - optional
This array contains objects that describe parameters that limit acceptable results.

 

Settings

This object is for configuring scenario properties.

json
  {
    "ScenarioName": "My Scenario Name",
    "ModelEffectiveDate": "1/7/2022",
    "DataValidationCascadeMode": "Continue",
    "EmailResults": true,
    "Pool": {
      "Id": "ATL1_42_PROD",
      "Name": "Name of service pool",
      "Description": "A long description of pool"
    }
  }

Attributes

ScenarioName - string - 42 max length
Name of this scenario.

INFO

Zypr auto-generates a unique Scenario Id. The Scenario Id and the actual date the scenario is created are added to Settings object.

ModelEffectiveDate - date (YYYY-MM-DD format) - optional
This date is represents both the effective date of the pool's resource data and the start date of the time-series outputs. If left blank, the start date is auto-assigned the same date the scenario was created.

TIP

Setting the ModelEffectiveDate property anchors the start date of generated time-series, which are contained in the ResourcesForecast object of the Scenario response object, to this date.

Generating a simulation without setting this date may result in different results when executing the same model on different dates or times.

DataValidationCascadeMode - string - optional
Determines whether the validation process stops or continues when a validation error occurs. 'Stop' is the default setting. 'Continue' permits the validation process to continue after encountering a validation error. However, the validation process is not guaranteed to finish all required validations. The 'Continue' setting may provide a quicker way to find data errors in a model. However, invalid data may trigger a downstream validation step to fail due to its reliance on valid data. A failed step will terminate the validation process.
EmailResults - boolean - optional
A notification emailed when simulation task completes. If the EmailResults property is true, the simulation task result will be attached to the notification email. Default is true.
Pool - object - optional
This object describes attributes of a pool.
Id - string - 24 max length - optional
Unique identifier of the pool.
Name - string - 42 max length - optional
Long string for describing pool.
Description - string - 64 max length - optional
Long string for describing scenario.

 

Simulation Rules

This SimulationRules object defines the objective function of a scenario with respect to cost scope and time.

json
  {
    "SimulationType": "OptimalYield",
    "SimulationCostScope": "All",
    "SolutionTargetTime": "5",
    "FindSolutionMetricType": "TotalCumulativeCostPerYear",
    "ServerReplacementTime": ""
  }

Attributes

SimulationType - string - required
Sets type of simulation.
Simulation Type Codes
CodeDescription
OptimalYieldObjective is to minimize total pool cost by finding ideal server turnover rates.
FixedTimeObjective is server turnover at predetermined, fixed-time schedule.
SimulationCostScope - string - required
Sets which resource costs are included in simulation.
Simulation Cost Scope Codes
CodeDescription
AllIncludes resource costs for hardware, software, power and facility space.
ServerAndPowerIncludes only costs for hardware and power.
ServerAndSoftwareIncludes only costs for hardware and software.
ExcludeFacilityExcludes facility space costs.
SolutionTargetTime - numeric - required
Sets a desired duration for time-series results. Unit is years.
FindSolutionMetricType - string - required
Sets metric used to find solution for SimulationType 'OptimalYield'
Solution Metric Codes
CodeDescription
TotalCumulativeCostUses cumulative cost of time-series.
TotalCumulativeCostPerYearUses cumulative cost per year of time-series.
ServerReplacementTime - numeric - conditionally required
Required when SimulationType property 'FixedTime' is selected. Sets preferred time of server refresh.

 

Evolution Rules

This EvolutionRules object defines the boundary conditions and rules for how pool server inventory is permitted to evolve.

json
  {
    "PoolUtilizationPercentCurrent": "63.5",
    "PoolUtilizationBoundaryPercentLower": "63.0",
    "PoolUtilizationBoundaryPercentUpper": "65.0",
    "ServiceDemandGrowthPercent": "20.5",
    "InventoryQueueBias":  "Auto",
    "LotConfiguration": {
        "LotType": "Rack",
        "ServerQty": "42",
        "ServerSize": "1",
        "RackSize":  "42"
    } 
  }

Attributes

ServerUtilizationPercentCurrent - numeric - required
Actual aggregate pool utilization percent at ModelRunDate (start time of scenario).
ServerUtilizationPercentBase - numeric - required
Targeted aggregate minimum utilization percent for pool.

INFO

This value constrains how much hardware capacity is added at an interval, within the time-series, when required capacity is re-evaluated and reset based upon service demand growth percent.

ServerUtilizationPercentPeak - numeric - required
Targeted aggregate maximum utilization percent for pool.

INFO

This value constrains aggregate peak utilization percent of pool. When reached, a new interval is triggered within the time-series.

ServiceDemandGrowthPercent - numeric - required
Expected service demand growth percent for pool.
InventoryQueueBias - string - optional
Queue order for how server inventory is sequenced for removal when SimulationType property is not set to 'FixedTime'. Queue order is based on unit performance rating. Default is 'Auto'.
Queue Bias Codes
CodeDescription
AutoZypr determines queue bias.
ServerServer unit queued least-to-best.
ProcessorProcessor unit queued least-to-best.
CoreCore unit queued least-to-best.
LotConfiguration - object - optional
Sets the inventory lot unit used in add/remove transactions. If not provided, default lot configuration is 1 server that is 1U size.

WARNING

Configuration is validated for consistency only.

For example, a valid configuration might be: RackSize property is 42, ServerSize property is 2, and ServerQty property is 21 or less. An invalid configuration would be RackSize property is 40, ServerSize property is 2, and ServerQty property is 22 (i.e., 2 x 22 = 44, which exceeds 40).

If LotType property is 'Server', only ServerSize property is required.

LotType - string - required
Sets unit basis for how server inventory is add and removed from pool.
Lot Type Codes
CodeDescription
RackRack is the add/remove unit
ServerServer is the add/remove unit
ServerQty - integer - optional
Quantity of servers when LotType property is set to 'Rack'. Default value is 1 when LotType property set to 'Server'.
ServerSize - integer - optional
The amount of space a server unit consumes in a rack in U unit. Valid values are 1, 2, 4. Default value is 1.
RackSize - integer - optional
Quantity of 1U servers in rack. Default value is 1.

 

Valuation Rules

This ValuationRule object defines parameters for defining the financial value of pool resources.

json
  {
    "DiscountPercent": 10,
    "IncludeServerResidualValue": true,
    "ResidualValueBidAskSpreadPercent": 40,
    "InitialInventoryIsNew": false
  }

Attributes

DiscountRate - numeric - required
Percentage used to convert future financial data into present value.
IncludeServerResidualValue - boolean - optional
Determines if server residual value is included in a server's net cost. The default value is 'true'.

INFO

When a server is removed from a pool, a residual value can be calculated and included to arrive at a server's net cost.

Residual value calculation is based upon the server's cost and performance rating indicated in the NewServerConfiguration object, which is treated as the current 'market rate' converted into a 'cost per performance unit'. The removed server's gross residual value is derived from this market rate and then adjusted downward to arrive at an approximate wholesale market rate using the ResidualValueBidAskSpreadPercent property.

InitialInventoryIsNew - boolean - optional
Determines if initial inventory in ServerInventory object is new and therefore the current server UnitCost property is applied. Default value is 'false'.

 

New Server Configuration

This NewServerConfiguration object sets the configuration of a new server that is added to a pool.

json
  {
    "ServerUnitCapacity": "130",
    "UnitCost": "10000",
    "ProcessorSetSize": "2",
    "CoreSetSize": "12",
    "ServerWatts": "435",
    "ServerSize": 1
  }

Attributes

ServerUnitCapacity - numeric - required
Scalar value representing server's relative performance rating.
UnitCost - numeric - required
Unit cost of server added to inventory.
ProcessorSetSize - integer - required
Quantity of physical processors contained in a server's cpu socket.
CoreSetSize - integer - required
Quantity of cores contained in physical processor.
ServerWatts - integer - required
Electrical power consumption rating in watts.
ServerSize - integer - required
Expressed as 'U' unit rating. Valid values are 1, 2, 4 (i.e., 1U, 2U, 4U).

 

Power Consumption Terms

This PowerConsumptionTerms object defines power consumption and its cost.

json
  {
    "PoolPowerDrawPercent": "80",
    "DatacenterPowerkWhCostRate": ".105",
    "DatacenterPUE": "1.6",
    "PowerCostInflationPercent": "0"
  }

Attributes

PoolPowerDrawPercent - numeric - required
Adjustment factor to tune actual consumption with respect to server watts rating.
DatacenterPowerkWhCostRate - numeric - required
Unit cost rate per kilowatt hour.
DatacenterPUE - numeric - required
Power Usage Effectiveness rating.
PowerCostInflationPercent - numeric - required
Annual inflation factor for DatacenterPowerkWhCostRate property.

 

Facility Consumption Terms

This FacilityConsumptionTerms object defines data center space consumption and its cost.

json
  {
    "PowerConsumptionMarkupPercent": "0",
    "ServerSize": 1,
    "ServerSizeUnitCost": "65",
    "RackSpaceInflationPercent": "2.75"
  }

Attributes

PowerConsumptionMarkupPercent - numeric - optional
Permits cost-basis for facility space to be based upon percentage markup of power consumption cost.
ServerSize - integer - required
Space unit utilized with respect to ServerSizeUnitCost property.
ServerSizeUnitCost - numeric - required
Unit cost per indicated unit space.
RackSpaceInflationPercent - numeric - required
Annual inflation factor for DatacenterPowerkWhCostRate property.

 

Software Resources

This SoftwareResources object defines the software stack registry and software inventory terms.

json
  {
    "SoftwareStackRegistry": [1,2,3],
    "SoftwareInventoryTerms": []
  }

WARNING

The SoftwareStackRegistry and SoftwareInventoryTerms objects are only intended to identify and describe the terms of software whose consumption is correlated to hardware performance or efficiency and has a meaningful financial cost. The registry is not intended to replicate SAM, TBM, or CMDB tools. Those tools often serve as a important source of information for Zypr.

Attributes

SoftwareStackRegistry - array of integers - required
Integer value corresponding to LicenseId property in SoftwareInventoryTerms object. Denotes the initial software stack for servers included in ServerInventory object.

TIP

A scenario only includes software costs for those software items contained in the software stack registry. The composition of the software stack may be modified at future points-in-time by using Jump Events to add and remove a license id from the software stack. All license ids contained in the registry must be included in the software inventory terms object.

Software Inventory Terms - array of objects - required
List of SoftwareItemTerms objects. Each object represents a unique software product whose use rights are based upon countable attributes of hardware (i.e., server, processor, core quantity).
Software Inventory Terms - array of objects - required
List of SoftwareItemTerms objects. Each object represents a unique software product whose use rights are based upon countable attributes of hardware (i.e., server, processor, core quantity).

 

Software Item Terms

This SoftwareItemTerms object defines software license terms and initial entitlement quantity.

json
  {
    "LicenseId": 1,
    "LicenseMetric": "Processor",
    "LicenseClass": "Perpetual",
    "ContractType": "Coterminous",
    "EntitlementExtremaResetBasis": "Never",
    "TermLength": 3,
    "AbsTermEndDate": "10/1/2023",
    "Fee": 6000,
    "PerpetualSupportPercent": 25,
    "InitialEntitlementQty": 128,
    "ConsumptionRules":  {
        "Id": "1",  
        "RequiredLicenseQty": "1"
    }
    
  }

Attributes

LicenseId - integer - required
Unique number for identifying the specific license terms.
LicenseMetric - string - required
Hardware item used by a vendor for counting license consumption.
License Metric Codes
CodeDescription
ServerA physical computer
ProcessorUnit that corresponds to a cpu socket
CoreProcessor unit within a processor
LicenseClass - string - required
License type.
License Class Codes
CodeDescription
PerpetualPermits indefinite usage
SubscriptionUsage time is finite

INFO

When set to 'Perpetual', Zypr auto-generates a corresponding support requirement. Quantities of support licenses are maintained and auto renewed as indicated by ContractType property.

ContractType - string - required
Sets how license is auto renewed as simulation evolves over time.
Contract Type Codes
CodeDescription
CoterminousUse term lengths are collectively linked to common term end date, which may be an annual settlement date or contract end date.
InstanceUse term is unique to when created.

INFO

Coterminous contract type indicates the term lengths, of existing and added (and possibly terminated) licenses, will have the same future date.

Zypr treats the contract end date as the baseline date to which any true-up or settlement (annual or end of contract term) is effective. These date distinctions are only important if EntitlementExtremaResetBasis is set to 'InterContract' or 'InterContract'.

Otherwise, Zypr will automatically renew existing software terms when the evolution time of a scenario exceeds the contract end date indicated by the AbsTermEndDate property. However, if future software terms are expected to change, a Jump Event can be added to define those expected changes.

'Instance' contract type renewals - if required - are assumed to correspond to the date in which they first incurred in the evolution process, which Zypr generates, and are further assumed to have a term of one year.

EntitlementExtremaResetBasis - string - optional
Used to indicate if a maximum license quantity count (position) may be reset to a lower level at a future true-up time such as annually or contract term end. This feature is only available to coterminous contracts. Default is 'Never'.
License Extrema Reset Basis Codes
CodeDescription
NeverMaximum quantity reset will not be evaluated by Zypr
InterContractMaximum quantity reset is evaluated at contract end date
IntraContractMaximum quantity reset is evaluated annually corresponding to contract end date

INFO

If your license agreement permits resetting entitled licenses to a lower level than a previously higher position, Zypr enables a reset at two-points-in-time: At an annual true-up (i.e., 'IntraContract'), or at contract term end (i.e., 'InterContract'). IntraContract reset assumes the effective date of an annual true-up is on the same month and day of the contract term end date.

TermLength - numeric - optional
Number of years a contract or license is in effect.
AbsTermEndDate - date - optional
Contract or license end date.
Fee - numeric - required
Amount paid per license. Fee may represent a one-time perpetual license fee, or the annualized equivalent price for a subscription.
PerpetualSupportPercent - numeric - optional
Percentage of one-time perpetual license fee that is paid annually.
InitialLicenseQty - integer - optional
Indicates the quantity of existing licenses. Default is null.

INFO

A null value instructs Zypr to set the initial license quantity position equal to the initial quantity of physical server inventory indicated by the LicenseMetric property. For example, if the LicenseMetric property is 'Core', the initial license quantity position will be set to the total number of cores contained in the *ServerInventory object.

If the InitialLicenseQty property is set to a number that is less than the initial quantity of physical inventory, a transaction (with associated costs) will be created to automatically increase license position to match required position (i.e., the corresponding physical inventory count).

If the InitialLicenseQty property is set to a number greater than the initial quantity of physical server inventory, Zypr will treat the starting license position as greater than initially required (i.e., excess resources).

ConsumptionRules - object - optional
This ConsumptionRules object defines how required license position is determined with respective to hardware configuration, transactions and inventory balances. Zypr uses a rule engine to evaluate consumption rules that may or may not involve "conditional logic." The code block below illustrates a rule with no conditional logic. How to define more complex rules is covered in the Software License Rule Engine section.
json
  {
    "ConsumptionRules":  {
        "Id": "1",  
        "RequiredLicenseQty": "1"
    }
  }

INFO

The code block above illustrates a single metric, defined by the LicenseMetric property, represents both the consumption measurement unit and required license quantity unit, with a common value of 1. If the ConsumptionRules property is omitted, Zypr will automatically generate this rule with the RequiredLicenseQty property set to 1.

 

Software License Rule Engine

Zypr's rule engine supports rule nesting using the Rules array property. Conditional rules always start with two root properties: Operator and Rules. When defining nested rules, it is important to ensure rules are mutually exclusive, yet account for all feasible values to which the rule might be applied.

At the root-level, the "Or" operator is mandatory and denotes its chid rules are mutually exclusive. At this level, the rules must account for all feasible "counting" outcomes and not overlap (i.e., an outcome can be evaluated as true for two or more rules). A vendor's specific counting methodology can then be further delineated using nested rules, as illustrated in the code block below.

For example, both consumption rule objects below correspond to a processor-based license (i.e., LicenseMetric property is 'Processor'). Each rules reads as follows:

First Rule Set:
"1 processor license is required when the core count per processor is less than or equal to 32, or 2 processor licenses when the core count per processor is greater than 32 per processor."
json
  
  "ConsumptionRules": {
      "Operator": "Or",
      "Rules": [
        {
          "Id": "1",
          "RequiredLicenseQty": 1,
          "MetricName": "CoreSetSize",
          "Operator": "LessThanOrEqual",
          "TargetValue": 32
        },
        {
          "Id": "2",
          "RequiredLicenseQty": 2,
          "MetricName": "CoreSetSize",
          "Operator": "GreaterThan",
          "TargetValue": 32
        }
      ]
    }

 

Second Rule Set:
"1 processor license is required when the core count per processor is less than or equal to 32, 2 processor licenses when the core count per processor is greater than 32 and less than 64, and 3 processor licenses when the core count per processor exceeds 64."
json
"ConsumptionRules": {
    "Operator": "Or",
    "Rules": [
      {
        "Id": "1",
        "RequiredLicenseQty": 1,
        "MetricName": "CoreSetSize",
        "Operator": "LessThanOrEqual",
        "TargetValue": 32
      },
      {
        "Id": "2",
        "Operator": "And",
        "RequiredLicenseQty": 2,
        "Rules": [
            {
              "Id": "2.1",
              "MetricName": "CoreSetSize",
              "Operator": "GreaterThan",
              "TargetValue": 32
            },
            {
              "Id": "2.2",
              "MetricName": "CoreSetSize",
              "Operator": "LessThanOrEqual",
              "TargetValue": 64
            }
        ]
      },
      {
        "Id": "3",
        "RequiredLicenseQty": 3,
        "MetricName": "CoreSetSize",
        "Operator": "GreaterThan",
        "TargetValue": 64
      }
    ]
  }

TIP

When defining nested rules, it is highly recommended you use outline numbering to identify rules. Zypr will only validate the rule Id property for duplicates. The Id solely exists for Zypr to identify to you, in a value you will recognize, a validation or other error related to the rule that prevents Zypr from executing.

Attributes

Operator - string - conditionally required
Logical operator for comparing multiple Rules. Valid values are: Or, And.
Id - string - required
Unique id for identifying different rules.
RequiredLicenseQty - integer - required
Required quantity of licenses if conditions logically resolve to true.
MetricName - string - required
Physical inventory target. Valid values are: ProcessorSetSize, CoreSetSize.
Operator - string - required
Comparison operator. Valid values are:
  • Equal
  • GreaterThan
  • GreaterThanOrEqual
  • LessThan
  • LessThanOrEqual
TargetValue - integer - required
Target value corresponding to MemberName property used to evaluate rule.

 

Server Inventory

This ServerInventory object defines a collection of initial server inventory of a pool.

json
  {
    "ServerInventory": []
  }

Attributes

ServerInventory - array of objects - required
List of ServerItem objects.

 

Server Item

This ServerItem object defines a quantity of servers with the same characteristics.

json
  {
    "ServerQty": 5,
    "ServerUnitCapacity": 72,
    "ServerWatts": 425,
    "ProcessorSetSize": 2,
    "CoreSetSize": 8,
    "InitialAge": 3.75,
    "ServerSize": 1
  }

Attributes

ServerQty - integer - required
Quantity of servers.
ServerUnitCapacity - numeric - required
Scalar value indicating server's relative efficiency rating.
ServerWatts - integer - required
Electrical power consumption rating in watts.
ProcessorSetSize - integer - required
Quantity of physical processors contained in a server's cpu socket.
CoreSetSize - integer - required
Quantity of cores contained in physical processor.
InitialAge - numeric - optional
Chronological age of servers. Only required when SimulationType property is set to 'FixedTime'

TIP

If SimulationType property is set to 'OptimalYield', Zypr will use initial age in age-related calculations. If initial age is not available, Zypr will use only those transactions in which Zypr can identify a date added and a date removed when calculating age-related metrics.

ServerSize - integer - required
Expressed as 'U' unit rating. Valid values are 1, 2, 4 (i.e., 1U, 2U, 4U).

 

Jump Events

This JumpEvents object defines a collection of jump events.

INFO

A jump event defines a discrete state change to a pool, at a desired time, and therefore how resource consumption, and corresponding transactions, may evolve over time.

Every jump event item included in the JumpEvents array must contain a valid EventType, a unique EventId, and a TriggerTime indicating when the jump event occurs. Each jump event type includes additional properties necessary to define their respective state change.

 

json
  {
    "JumpEvents": []
  }

Attributes

JumpEvents - array of objects - required
List of jump events that describe discrete changes to the evolution state of pool resources. Valid jump events are listed in the Jump Event Types object reference.

 

Constraints

This Constraints object defines a collection of Constraint objects that limit the feasible solution space.

json
  {
    "Constraints": [
      {
        ConstraintTypeName : {}
      }
    ]
  }

Attributes

Constraints - array of objects - required
List of constraint items to limit feasible solutions.
ConstraintTypeName - string - required
Name of constraint object type. Valid values are: HardwareBalance, PowerUsage.

 

Constraint

Purpose

This Constraint object defines a constraint type.

INFO

A constraint limits the feasible solution space, and is expressed by stating what is not permitted:

For example, the code block below reads as follows: "Server cumulative inventory balance is not permitted GreaterThan than 128 servers Before 2.5 years."

As a result, all solutions that have a cumulative server balance from time 0 to 2.5 years (exclusive) will not be considered a feasible result.

 

json
  {
    "HardwareBalance": {
      "Id": 1,
      "MetricName": "Server",
      "IsTimeRestricted": true,
      "TargetTime": 2.5,
      "TimeConstraintOperator": "Before",
      "MetricTargetValue": 128,
      "MetricConstraintOperator": "GreaterThan"
    }
  }

Attributes

Id - integer - required
Unique number to identify constraint.
MetricName - string - required
Targeted metric unit for constraint type. Valid values are: Server, Processor, Core.
IsTimeRestricted - boolean - required
If 'true', object requires a target time.
TargetTime - integer - optional
Time within time-series when the constraint is invoked.
TimeConstraintOperator - string - required
Comparison operator to set constraint scope with respect to time.
Valid values are:
  • Before
  • BeforeOrAt
  • AtOrAfter
  • After
  • At
  • NotAt
  • Any
MetricTargetValue - integer optional
Value that sets desired limit.
MetricConstraintOperator - string - required
Comparison operator to set constraint scope with respect to selected metric unit.
Valid values are:
  • LessThan
  • LessThanOrEqual
  • GreaterThan
  • GreaterThanOrEqual
  • NotEqual
  • Equal

Ravello Analytics, LLC