NetworkEquipment

  • 15.5
This article is may not be up to date with the latest stable release of M4.

Description

The NetworkEquipment endpoint provides the API consumer with access to methods pertaining to equipment and equipment templates. The endpoint allows consumers to load equipment/equipment template records, search for equipment templates and create equipment from a specified template.

Methods

URL base/NEM/NetworkEquipment/Specification
Action GET
Description Returns a data dictionary that details the available web service methods related to NetworkEquipment.
Parameters None
 Returns  A JSON object with method descriptions
Sample Return Object 
        [
        {
            "HttpAction": "Get",
            "MethodName": "GetEquipmentTemplate",
            "Description": "Returns the record for a single 'Equipment Template' given the passed in ID value (see Path).",
            "Path": "base/NetworkEquipment/GetEquipmentTemplate/25032"
        },
        {
            "HttpAction": "Get",
            "MethodName": "GetEquipmentTemplates",
            "Description": "Returns the records for all 'Equipment Templates' in the system.",
            "Path": "base/NetworkEquipment/GetEquipmentTemplates/25032"
        },
        {
            "HttpAction": "Post",
            "MethodName": "GetEquipmentTemplateBySearch",
            "Description": "Returns the records for all 'Equipment Templates' in the system that match the search criteria. Each field is treated as a wildcard field. Please note that, at least one field, must be specified.",
            "Format": {
                "Category": "Racks",
                "Manufacturer": "Steel Enterprises",
                "ModelNumber": "VT3423434"
            }
        },
        {
            "HttpAction": "Post",
            "MethodName": "GetEquipment",
            "Description": "Returns the underlying 'Equipment' record given the equipment ID and equipment type. Valid equipment types are: 'Bay', 'Card', 'Shelf'.",
            "Format": {
                "EquipmentID": 45,
                "EquipmentTableType": "Card"
            }
        },
        {
            "HttpAction": "Post",
            "MethodName": "CreateEquipment",
            "Description": "Creates one or more equipment items from the specified equipment template and returns all Bays, Cards and Shelves created by the method call.",
            "Format": {
                "EquipmentTemplateID": 389,
                "SerialNumber": "VT235323245",
                "Description": "Creates a new bay and sub-bay"
            }
        }
    ]
URL base/NEM/NetworkEquipment/GetEquipmentTemplate/ID
Action GET
Description Returns an Equipment Template when given the ID of a valid template in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of an Equipment Template in the M4 database.
Returns A JSON Equipment Template data object
Sample Return Object 
        {
            "ID": 1,
            "Category": "Category Name",
            "Manufacturer": "Acme Enterprises, Inc.",
            "ModelNumber": "MK324234342",
            "OSRevision": "1.2.1.4",
            "Document": "Additional text",
            "EquipmentType": "Equipment Type",
            "Electronic": "Additional Info"
        }
URL base/NEM/NetworkEquipment/GetEquipmentTemplates
Action GET
Description Returns a list of Equipment Templates in the M4 database.
Parameters None
Returns A list of JSON Equipment Template data objects
Sample Return Object 
[
  {
        "ID": 1,
        "Category": "Category Name",
        "Manufacturer": "Acme Enterprises, Inc.",
        "ModelNumber": "MK324234342",
        "OSRevision": "1.2.1.4",
        "Document": "Additional text",
        "EquipmentType": "Equipment Type",
        "Electronic": "Additional Info"
    },
    {
        "ID": 2,
        "Category": "Category Name",
        "Manufacturer": "General Builders, Inc.",
        "ModelNumber": "VT3224",
        "OSRevision": "2.2.1",
        "Document": "Additional text",
        "EquipmentType": "Equipment Type",
        "Electronic": "Additional Info"
    },
    {
        "ID": 3,
        "Category": "Category Name",
        "Manufacturer": "National Associates, LLC.",
        "ModelNumber": "23423423423",
        "OSRevision": "3.4",
        "Document": "Additional text",
        "EquipmentType": "Equipment Type",
        "Electronic": "Additional Info"
    }
]
URL base/NEM/NetworkEquipment/GetEquipmentTemplateBySearch
Action POST
Description Returns the records for all 'Equipment Templates' in the system that match the search criteria. Each field is treated as a wildcard field. Please note that, at least one field, must be specified.
Parameters
Name Required? Type Description
Category *No String The category to be searched for the Equipment Template.
Manufacturer *No String The manufacturer to be searched for the Equipment Template.
ModelNumber *No String The model number to be searched for the Equipment Template.
Sample JSON Package 
{
    "Category": "Category",
    "Manufacturer": "Steel Enterprises",
    "ModelNumber": "VT3423434"
}
Returns A list of JSON Equipment Template data objects
Sample Return Object 
[
  {
        "ID": 1,
        "Category": "Category",
        "Manufacturer": "Steel Enterprises",
        "ModelNumber": "VT3423434",
        "OSRevision": "1.2.1.4",
        "Document": "Additional text",
        "EquipmentType": "Equipment Type",
        "Electronic": "Additional Info"
    },
    {
        "ID": 2,
        "Category": "Category",
        "Manufacturer": "Steel Enterprises",
        "ModelNumber": "VT3423434",
        "OSRevision": "2.2.1",
        "Document": "Additional text",
        "EquipmentType": "Equipment Type",
        "Electronic": "Additional Info"
    }
]
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
 
All Fields:
  • *At least one field must be specified. All fields combine to form a boolean 'AND' search
  • The search terms are automatically assumed to be wildcard searches. Invalid characters will be blocked. Invalid characters are: %_[]^
URL base/NEM/NetworkEquipment/GetEquipment
Action POST
Description Returns the underlying 'Equipment' record (Bay, Card or Shelf) given the equipment ID and equipment type.
Parameters
Name Required? Type Description
EquipmentID Yes Integer An integer value representing the Equipment ID of the record in the M4 database.
EquipmentTableType Yes String The type of equipment to be returned. Valid values are: Bay, Card or Shelf
Sample JSON Package 
    {
        "EquipmentID": 45,
        "EquipmentTableType": "Card"
    }
Returns A JSON Bay, Card or Shelf data object (only one object returned)
Sample Return Object
Bay Object
    {
        "ID": 1,
        "Spacing": 28,
        "RackSpace": null,
        "BayLink": 2,
        "IPAddress": null,
        "SubBay": "YES",
        "UniqueBayName": null,
        "DefaultZoom": null,
        "NetworkTemplateLink": 23,
        "Shelf": null,
        "Comments": null,
        "Height": 45,
        "Width": 33,
        "M4LinkTable": null,
        "M4LinkDBKey": null,
        "Description": "Description",
        "Details": null,
        "PostingState": null,
        "WONumber": null,
        "DatePlaced": null,
        "DateRetired": null,
        "FCCCode": null,
        "TaxID": null,
        "Manufacturer": "Manufacturer",
        "ModelNumber": "Model Number",
        "SerialNumber": "Serial Number",
        "OSRevision": "OS revision",
        "Category": "Category",
        "TemplateLink": 38
    }
Card Object
    {
        "ID": 22,
        "ShelfLink": 0,
        "DrawerLink": null,
        "Slot": 45,
        "AccessLines": null,
        "ServiceType": 16,
        "CardRows": null,
        "CardColumns": null,
        "Drawer": "YES",
        "Fill": null,
        "PercentFill": null,
        "ServiceLine": null,
        "LineLimit": null,
        "CLLI": null,
        "SHELFNUM": null,
        "SubSlot": null,
        "Height": 45,
        "Width": 33,
        "M4LinkTable": null,
        "M4LinkDBKey": null,
        "Description": "Description",
        "Details": null,
        "PostingState": null,
        "WONumber": null,
        "DatePlaced": null,
        "DateRetired": null,
        "FCCCode": null,
        "TaxID": null,
        "Manufacturer": "Manufacturer",
        "ModelNumber": "Model Number",
        "SerialNumber": "Serial Number",
        "OSRevision": "OS revision",
        "Category": "Category",
        "TemplateLink": 38
    }
Shelf Object
    {
        "ID": 38,
        "Spacing": 28,
        "BayLink": 0,
        "TopOfBox": 48,
        "LeftOfBox": 98,
        "RackSpace": null,
        "Size": 18,
        "Slots": 12,
        "Orientation": 90,
        "Equipment": "YES",
        "SubShelf": "NO",
        "Fill": null,
        "Backview": "YES",
        "CardLink": 0,
        "ShelfLink": null,
        "Slot": 45,
        "NetworkTemplateLink": 23,
        "CustLink": null,
        "Height": 45,
        "Width": 33,
        "M4LinkTable": null,
        "M4LinkDBKey": null,
        "Description": "Description",
        "Details": null,
        "PostingState": null,
        "WONumber": null,
        "DatePlaced": null,
        "DateRetired": null,
        "FCCCode": null,
        "TaxID": null,
        "Manufacturer": "Manufacturer",
        "ModelNumber": "Model Number",
        "SerialNumber": "Serial Number",
        "OSRevision": "OS revision",
        "Category": "Category",
        "TemplateLink": 38
    }
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
 
EquipmentID:
  • Must exist in the M4 database as a valid equipment record (as it relates to the EquipmentTableType parameter)
EquipmentTableType:
  • Must be one of three values: Bay, Card, Shelf
URL base/NEM/NetworkEquipment/CreateEquipment
Action POST
Description Creates one or more equipment items from the specified equipment template and returns all Bays, Cards and Shelves created by the method call.
Parameters
Name Required? Type Description
EquipmentTemplateID Yes Integer An integer value representing the Equipment Template ID of the record in the M4 database.
SerialNumber No String The serial number of the new equipment.
Description No String A description of the new equipment.
Sample JSON Package 
        {
            "EquipmentTemplateID": 389,
            "SerialNumber": "VT235323245",
            "Description": "Creates a new bay and sub-bay"
        }
Returns A list of JSON Bay, Card and/or Shelf objects created during the method call.
Sample Return Object 
        {
            "CreateDate": "2019-07-22T03:07:39.21",
            "Bays": [
                {
                    "ID": 1,
                    "Spacing": 28,
                    "RackSpace": null,
                    "BayLink": 2,
                    "IPAddress": null,
                    "SubBay": "YES",
                    "UniqueBayName": null,
                    "DefaultZoom": null,
                    "NetworkTemplateLink": 23,
                    "Shelf": null,
                    "Comments": null,
                    "Height": 45,
                    "Width": 33,
                    "M4LinkTable": null,
                    "M4LinkDBKey": null,
                    "Description": "Description",
                    "Details": null,
                    "PostingState": null,
                    "WONumber": null,
                    "DatePlaced": null,
                    "DateRetired": null,
                    "FCCCode": null,
                    "TaxID": null,
                    "Manufacturer": "Manufacturer",
                    "ModelNumber": "Model Number",
                    "SerialNumber": "Serial Number",
                    "OSRevision": "OS revision",
                    "Category": "Category",
                    "TemplateLink": 38
                },
                {
                    "ID": 3,
                    "Spacing": 34,
                    "RackSpace": null,
                    "BayLink": 2,
                    "IPAddress": null,
                    "SubBay": "YES",
                    "UniqueBayName": null,
                    "DefaultZoom": null,
                    "NetworkTemplateLink": 23,
                    "Shelf": null,
                    "Comments": null,
                    "Height": 45,
                    "Width": 33,
                    "M4LinkTable": null,
                    "M4LinkDBKey": null,
                    "Description": "Description",
                    "Details": null,
                    "PostingState": null,
                    "WONumber": null,
                    "DatePlaced": null,
                    "DateRetired": null,
                    "FCCCode": null,
                    "TaxID": null,
                    "Manufacturer": "Manufacturer",
                    "ModelNumber": "Model Number",
                    "SerialNumber": "Serial Number",
                    "OSRevision": "OS revision",
                    "Category": "Category",
                    "TemplateLink": 38
                }
            ],
            "Cards": [
                {
                    "ID": 1,
                    "ShelfLink": 0,
                    "DrawerLink": null,
                    "Slot": 45,
                    "AccessLines": null,
                    "ServiceType": 16,
                    "CardRows": null,
                    "CardColumns": null,
                    "Drawer": "YES",
                    "Fill": null,
                    "PercentFill": null,
                    "ServiceLine": null,
                    "LineLimit": null,
                    "CLLI": null,
                    "SHELFNUM": null,
                    "SubSlot": null,
                    "Height": 45,
                    "Width": 33,
                    "M4LinkTable": null,
                    "M4LinkDBKey": null,
                    "Description": "Description",
                    "Details": null,
                    "PostingState": null,
                    "WONumber": null,
                    "DatePlaced": null,
                    "DateRetired": null,
                    "FCCCode": null,
                    "TaxID": null,
                    "Manufacturer": "Manufacturer",
                    "ModelNumber": "Model Number",
                    "SerialNumber": "Serial Number",
                    "OSRevision": "OS revision",
                    "Category": "Category",
                    "TemplateLink": 38
                },
                {
                    "ID": 2,
                    "ShelfLink": 0,
                    "DrawerLink": null,
                    "Slot": 45,
                    "AccessLines": null,
                    "ServiceType": 16,
                    "CardRows": null,
                    "CardColumns": null,
                    "Drawer": "YES",
                    "Fill": null,
                    "PercentFill": null,
                    "ServiceLine": null,
                    "LineLimit": null,
                    "CLLI": null,
                    "SHELFNUM": null,
                    "SubSlot": null,
                    "Height": 45,
                    "Width": 33,
                    "M4LinkTable": null,
                    "M4LinkDBKey": null,
                    "Description": "Description",
                    "Details": null,
                    "PostingState": null,
                    "WONumber": null,
                    "DatePlaced": null,
                    "DateRetired": null,
                    "FCCCode": null,
                    "TaxID": null,
                    "Manufacturer": "Manufacturer",
                    "ModelNumber": "Model Number",
                    "SerialNumber": "Serial Number",
                    "OSRevision": "OS revision",
                    "Category": "Category",
                    "TemplateLink": 38
                }
            ],
            "Shelves": [
                {
                    "ID": 1,
                    "Spacing": 28,
                    "BayLink": 0,
                    "TopOfBox": 48,
                    "LeftOfBox": 98,
                    "RackSpace": null,
                    "Size": 18,
                    "Slots": 12,
                    "Orientation": 90,
                    "Equipment": "YES",
                    "SubShelf": "NO",
                    "Fill": null,
                    "Backview": "YES",
                    "CardLink": 0,
                    "ShelfLink": null,
                    "Slot": 45,
                    "NetworkTemplateLink": 23,
                    "CustLink": null,
                    "Height": 45,
                    "Width": 33,
                    "M4LinkTable": null,
                    "M4LinkDBKey": null,
                    "Description": "Description",
                    "Details": null,
                    "PostingState": null,
                    "WONumber": null,
                    "DatePlaced": null,
                    "DateRetired": null,
                    "FCCCode": null,
                    "TaxID": null,
                    "Manufacturer": "Manufacturer",
                    "ModelNumber": "Model Number",
                    "SerialNumber": "Serial Number",
                    "OSRevision": "OS revision",
                    "Category": "Category",
                    "TemplateLink": 38
                },
                {
                    "ID": 5,
                    "Spacing": 28,
                    "BayLink": 0,
                    "TopOfBox": 48,
                    "LeftOfBox": 98,
                    "RackSpace": null,
                    "Size": 18,
                    "Slots": 12,
                    "Orientation": 90,
                    "Equipment": "YES",
                    "SubShelf": "NO",
                    "Fill": null,
                    "Backview": "YES",
                    "CardLink": 0,
                    "ShelfLink": null,
                    "Slot": 45,
                    "NetworkTemplateLink": 23,
                    "CustLink": null,
                    "Height": 45,
                    "Width": 33,
                    "M4LinkTable": null,
                    "M4LinkDBKey": null,
                    "Description": "Description",
                    "Details": null,
                    "PostingState": null,
                    "WONumber": null,
                    "DatePlaced": null,
                    "DateRetired": null,
                    "FCCCode": null,
                    "TaxID": null,
                    "Manufacturer": "Manufacturer",
                    "ModelNumber": "Model Number",
                    "SerialNumber": "Serial Number",
                    "OSRevision": "OS revision",
                    "Category": "Category",
                    "TemplateLink": 38
                }
            ]
        }
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
 
EquipmentTemplateID:
  • Must exist in the M4 database as a valid equipment template
  • The template must link to valid equipment.
  • The underlying equipment must be Bay, Card and/or Shelves.
  • Sub-shelfs must have a template record that defines a sub-bay

Was this article helpful?

Yes No

Related Articles