UNROUTED

DRAFT

Workload is defined but not included in a Routing Request (i.e. not routed).

ANALYZING

PENDING

Workload included in a Routing Request.

BOOKED

PENDING to COMMITTED to LATE to COMPLETED

When routed to a full control hosting venue with a future date, associated Booking is in PENDING state until it is included in the analytics through an environment refresh, when it is changed to COMMITTED. Changes to LATE when the incoming workload is late (i.e. expected_date arrives and late_days is > 0). The Booking becomes COMPLETED when the corresponding workload comes online and is auto-reconciled with the environment refresh.

When routed to a guest-level hosting venue with an immediate or future date, associated Booking is in PENDING state until it is included in the analytics through an environment refresh, when it is changed to COMMITTED. Changes to LATE when the incoming workload is late (i.e. expected_date arrives and late_days is > 0). The Booking becomes COMPLETED when the corresponding workload comes online and is auto-reconciled with the environment refresh.

When routed to a non-control hosting venue, the associated Booking becomes COMMITTED (bypassing the PENDING state as the analytic refresh is not applicable). It then changes to LATE when the incoming workload is late (i.e. expected_date arrives and late_days is > 0). The Booking becomes COMPLETED when manually updated through a PUT request.

PLACED

(PENDING to) COMMITTED to LATE to COMPLETED

These states only apply when routed to a full control hosting venue.

A workload is PLACED in the following cases:

• workload routed with today's date
• incoming workload arrives before extended expected date (including <n> days of grace defined by late_days)
• a GET request is executed on an individual Workload in BOOKED status with expected_date of today (or expected_date has passed but Booking has not EXPIRED).

Associated Booking is in PENDING state until it is included in the analytics through an environment refresh, when it changes to COMMITTED. Changes to LATE when incoming workload is late (i.e. expected_date arrives and late_days is > 0). Changes to COMPLETED only when the incoming workload is reconciled. See Placement and Option for Placement for further details.

REJECTED

DRAFT

Could not route or reserve space.

EXPIRED

No incoming workload by the extended expected date (including the <n> days of grace defined by late_days).

N/A

CANCELLED

Routing Request deleted.

Get Collection

GET /workloads

None

Workload Collection of [id, name, href]

Default Sort By is defined as:
?sort_by=expected_date

Common Operations is supported. Note that it returns all status values of the collection, filtered or not, as if the collection was not filtered.

Example: Rechecking Health Status for Placed Workloads

Get Individual

GET /workloads/<id>

None

Workloads: Resource Elements

Retrieve the Workload elements of the specified id. If the Workload is in BOOKED status and expected_date is today (or passed), the Workload status will be updated to REJECTED (if the associated Booking has EXPIRED) or PLACED (with a recommended host placement).

Example: Getting an Individual Workload

Create Individual

POST /workloads

Workloads: Resource Elements

Workloads: Resource Elements

A Workload can be created in one of two ways:

• using this POST request on Workloads
• using the POST request of its Routing Request, and specifying the same Workload elements as a POST on the Workload

Example: Creating a Workload with Preferences, Example: Creating a Workload with Multiple Disks, Example: Creating a Workload with License Requirements

Create Multiple

POST /workloads

Workloads: Resource Elements

With "num_copy" : <number> specified

Workloads: Resource Elements

Similar to the Create Individual operation, but specifying the number of Workloads to create using "num_copy" : <number> with no limit to the number of instances created at a time. The names of the Workloads are auto-generated by appending a number after name. For example, if name=VM, then the generated names would be VM1, VM2, etc.

Example: Creating Multiple Workloads

Modify Individual

PUT /workloads/<id>

Workloads: Resource Elements

Only elements marked "M" in the Create/Mod column can be modified

Workloads: Resource Elements

A Workload that is not in PLACED state can be modified through the PUT command. Only the name can be modified when the Workload is in the ANALYZING or BOOKED state. The disks > pref_datastore element can be modified when the Workload is in the UNROUTED state.

If the catalog_spec is specified (even if it is not different), then other elements are defaulted as documented above unless explicitly overridden again.

Example: Modifying a Workload, Example: Unsetting the Preferred Environment

Modify Multiple

PUT /workloads/multiple

workloadIds: [<id>, <id>,…], workload: {Workloads: Resource Elements}

Only elements marked "M" in the Create/Mod column can be modified, except for name and pref_datastore

Workloads: Resource Elements

Workloads that are in UNROUTED or REJECTED states can be modified by one PUT command. This API collectively updates all specified Workloads, or fails for all Workloads. If the catalog_spec is specified (even if it is not different), then other elements are defaulted as documented above unless explicitly overridden again.

Example: Modifying Multiple Workloads, Example: Modifying Multiple Workloads and Their Attributes

Delete Individual Workload

DELETE /workloads/<id>

None

None

Only Workloads in UNROUTED state can be deleted. When the Workload is deleted, its associated Booking is also deleted. An error is thrown if the Workload is in any other state.

For details when its owning Routing Request is deleted, see Routing Requests.

Delete Multiple Workloads

DELETE /workloads

workloadIds: [<id>, <id>,…]

None

Similar to deleting a single Workload above, however, this command deletes multiple Workloads in one call.

Example: Deleting Multiple Workloads

Delete Individual Attributes

DELETE /workloads/<id>/attributes

[id, value]

Where value is only required to delete the attribute value

None

If just the id of the attribute is specified, deletes all attribute id-name-value settings with that id. If id and value are specified, then deletes only that attribute with matching value.

The id corresponds to an attribute id in the attributes array. This request is valid in any state.

If the attribute id or value does not exist, then that specific delete is simply ignored.

If any deleted item fails to delete, then no delete is performed at all.

For example:

[
   { "id": "attr_2", "value": "Capps"},
   { "id": "state_power"}
]

Example: Deleting an Attribute from a Specific Workload

id, name, href

strings

CM-R for name

S by name

F by name

See ID, Name and Self Reference (id, name, href). The name is the expected system name of the incoming VM, required for auto-reconciliation. For details, see section Auto-Reconciliation of Systems of Booking Overview (Help Topic ID 230350).

attributes

[id, name, value]

CM

F only as that defined in cfg\bookings\bookings-config.xml

On a create or modify request, defines the Fit for Purpose attributes of the incoming system. If the attribute name or value is incorrectly specified, an error is returned and the Workload object is not created.

For a create/modify, only the name-value pairs are required. The id is not required.

For a single-valued attribute, if the name-value pair is defined more than once, then only the first occurrence is used and the second one is ignored.

For a multi-valued attribute, the name-value pair can be specified multiple times as required for the same named attribute. Duplicates when specifying the same value more than once for the same named attribute are ignored.

With the create request, some attributes are given default values. With the modify request, specifying a new attribute will be added, a single-valued attribute will be modified, and a multi-valued attribute will be appended with the new value.

On a GET request, only those attributes that have values are returned.

The attributes you can define are found in the cfg\bookings\bookings-config.xml. id is defined in that file and name corresponds to the actual field label. For example:
{
  "id": "BOOKING_USED_DISKSPACE",
  "name": "Used Space (MB)",
  "value": "20480"
}

To create or modify, only the name-value pairs are required:
{
  "name": "Used Space (MB)",
  "value": "20480"
}

To filter on an attribute, use attribute.id. For example, to filter all Workloads that belong to Level 1 Security Zone:
/workloads/?attribute.attr_SecurityZone=Level 1

booking

id, name, href

This is the link to the associated Booking.

catalog_spec

string

CM

S

F

Used to define the Catalog Reference Name, which corresponds to a specific Catalog Specification (see Catalog Specifications). When specified, this automatically sets other elements of the Workload, as documented herein. If not specified, this is defaulted to that defined by configuration seting API Default Catalog Specification (parameter key rest.api.catalogSpec.default). Must be a valid catalog name; otherwise, an error is returned.

catalog_spec_id

id

F

Used to return the ID of the catalog_spec.

control_environment

id, name, href, icon

F using control_environment_id

This is the link to the associated Control Environment where the workload was placed. Set if and only if the Workload has been routed (i.e. status is PLACED or BOOKED).

cpu_entitlement

number

CM

S

F

The eCPU. If not specified, defaulted to vcpu if vcpu is specified; otherwise, defaulted to that associated with catalog_spec.

creation_time

number

S

F

This is set to the date and time the Workload was created, in UTC.

description

string

CM

An arbitrary string that describes the workload.

Kept in sync with the comments element defined by its associated Booking.

disks

[name, provisioned_space, used_space, pref_datastore, attributes[]]

CM

pref_datastore cannot be updated in a modify multiple workloads operation

F only by number_of_disks

An array of disk requirements, with sizes and tier capabilities. One disk is defined by default. When modifying this array, you must specify all disks as the new array replaces the existing one. Defaulted to that of the associated catalog_spec, if defined.

Each disk is defined as follows:

• name—name of the disk
• provisioned_space—provisioned space in MB
• used_space—used space in MB
• attributes: [id, name, value]—id, name and value of the datastore attributes. The id is mapped to its display name (e.g. "attr_DatastoreTier" is mapped to "Datastores") and can be determined by performing GET /sensors. An example of id, name and value:

{

  "id": "attr_DatastoreTier",

  "name": "Datastore Tier",

  "value": "Gold"

}

• pref_datastore—preferred datastore for the disk (optional: only returned if set)

See Assessing Datastore for datastore placement details.

expected_date

number

CM

S

F using expected_date_to, expected_date_from

The date this workload will arrive in UTC. The time portion is ignored and always set to 04:00:00.

If the Workload is created independently, using its own POST request, the expected_date is set by default to today.

If the Workload is created within a POST request of a Routing Request, the expected_date is set by default to that of the Routing Request.

When routing the request, the expected_date is taken from the Routing Request, and not in the Workload.

For filtering workloads with arrival date before a specific date, use the expected_date_to option. To return all the workloads expected to arrive from a particular date, use the expected_date_from option. To return workloads with expected arrival dates within a range, use the expected_date_from=<start_date>&expected_date_to=<end_date> option.

host

string

F

The recommended host where this workload should be placed. Set if and only if the Workload has been routed (i.e. status is BOOKED with an analysis refresh or PLACED). Once defined, this host recommendation is subsequently updated, for the cases as described in State Diagrams for Demand. Note that this is not the actual host placement, but a recommendation.

infrastructure_group

id, name, href

F using infrastructure_group_id, infrastructure_group

This is the link to the associated Infrastructure Group where the workload was placed. Set, if and only if, the Workload has been routed (i.e. status is PLACED or BOOKED).

Note that when filtering on Infrastructure Groups, you must use the element infrastructure_group_id with a UUID specified or element infrastructure_group with a name specified.

late_days

number

To allow for a late incoming workload, this is the number of days to hold the reservation after the expected_date. This element is defaulted to that defined by configuration setting Default Number of Days to Hold a Booking Reservation after the Planned Start Date (parameter key default.num.days.to.hold.booking.reservation) of category 25. Advanced - Booking Reservation Settings. Specify 0 to define no grace period.

For details on late bookings, see Late Bookings.

memory

number

CM

S

F

The benchmark type Memory (score type Total Memory (MB)), defaulted to that of the associated catalog_spec.

number_days_to_expiry

number

not applicable

The number of remaining days before expiry (which is calculated as expected_date - today's date + late_days). This element is returned only when the associated Booking is "COMMITTED". This element is updated on every analysis refresh.

number_of_disks

number

not applicable

S

F

The number of disks defined in the disks array. This element is only used for filtering.

owner

string

CM

S

F

Used to define the owner or Customer Name of this Workload. If not set, this field is set to the user who is creating the Workload.

owner_email

string

CM

F

The email address of the owner.

Kept in sync with the requester_email element defined by its associated Booking.

os

string

S

F

The Operating System Name, defined to that of the associated catalog_spec, e.g. "Linux".

pref_control_environment

id, name, href, icon

CM using id

A link to the Control Environment, where the Workload is preferred to be placed.

To specify this element, use the format as shown in this example:

"pref_control_environment": {
"id": "85772672-0388-4c34-939f-156f98b420bd"
}

To unset this element, use:

"pref_control_environment": {
"id": "__DELETE__"}

pref_infrastructure_group

id, name, href

CM using id

A link to the preferred Infrastructure Group, where the Workload is preferred to be placed.

To specify this element, use the format as shown in this example:

"pref_infrastructure_group": {
  "id": "9475b61b-5378-4a65-8e27-3cf488583f8f"
}

To unset this element, use:

"pref_infrastructure_group": {
  "id": "__DELETE__"}

profile_strength

number [-1..100]

This is set to the profile strength of the Workload request and is only set when the Workload status is UNROUTED. -1 means insufficient data.

project

string

CM

F

Used to define the Project. If not set, the Project is defined as "__Unknown__".

provisioned_space

number

not applicable

S

F

The sum of the provisioned space for the disks within the Workload (i.e. sum of the provisioned_space in MB of the disk array). Defaulted to that of the associated catalog_spec.

routing_request

href

A link to the Routing Request that is associated with this Workload.

sensors

[id, name, type, href, host_name]

The recommended Sensor object placement. Set if and only if the Workload has been routed (i.e. status is PLACED or BOOKED). Once defined, this sensor recommendation is subsequently updated, for the cases as described in State Diagrams for Demand.

If there are no sensors, the empty list is returned.

• id−sensor id
• name−name of the sensor
• type−sensor type (e.g. "datastore")
• href−sensor href
• hostname−display name of the sensor

For Sensor element details, see Sensors including Datastores, Physical Storage, Resource Pools: Resource Elements.

status

string

S

F

The filter-metadata returns status_value with all 5 possible states

The status of the Workload. See State Diagrams for Demand for state details.

If the Workload is associated with a Routing Request, this is the status of the Routing Request:

• "ANALYZING"
• "PLACED"
• "BOOKED"
• "REJECTED"

If this Workload is not associated with any Routing Request, then the status is:

• "UNROUTED"−initial state when Workload is not part of any Routing Request

status_reason

string

F

This is not returned with the filter-metadata request, as this is free-form text.

Explanation of the status. This is populated when the status is REJECTED or forced to PLACED state, and takes on the same value as that of the Routing Request.

used_space

number

not applicable

S

F

The sum of the used space for the disks within the Workload (i.e. sum of the used_space in MB of the disk array). Defaulted to that of the associated catalog_spec.

vcpu

number

CM

S

F

The total vCPUs, defaulted to that of the associated catalog_spec. If specified, automatically updates cpu_entitlement to the same value if cpu_entitlement is not itself specified.

workload_profile

string

CM

F

Used to define the Workload Profile (see Workload Profiles). If not specified, this is defaulted to that defined by the catalog_spec. Must be a valid Workload Profile; otherwise, an error is returned. Note that if a UUID is returned, then this is a workload created from a transform analysis (i.e. Workoad Profile is a system name in the Booking Manager).