Skip to main content

Inventory Device Operation

The Inventory Device Operation API provides endpoints for managing operational changes and updates to devices within your inventory system. These endpoints handle device state modifications, configuration updates, and operational status changes, enabling real-time management of your device infrastructure.

Base URL: https://control.zequenze.com/api/v1

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device Operation API category is designed for managing operational aspects of devices in your inventory system. This API enables you to update device configurations, modify operational states, change device assignments, and manage device lifecycle events.

Common use cases include:

  • Updating device operational status (active, maintenance, decommissioned)
  • Modifying device configuration parameters
  • Changing device assignments to different locations or users
  • Updating device metadata and operational properties
  • Managing device maintenance schedules and operational notes

This API works in conjunction with the broader inventory management system, allowing you to maintain real-time operational visibility and control over your device infrastructure. Operations performed through these endpoints typically trigger audit logs and may affect device monitoring and alerting systems.

Key concepts:

  • Device Operations: Structured updates that modify device state or configuration
  • Operational Status: Current state of device availability and functionality
  • Device Assignments: Location, user, or organizational unit associations
  • Configuration Updates: Changes to device-specific operational parameters

Endpoints

PUT /inventory_device_operation/{id}/

Description: Updates operational parameters and status for a specific device in the inventory. This endpoint allows you to modify device configurations, change operational status, update assignments, and manage device lifecycle states. Use this endpoint when you need to reflect real-world changes to device operations, maintenance status, or configuration parameters.

Use Cases:

  • Updating a device from "active" to "maintenance" status during scheduled downtime
  • Changing device location assignments when equipment is moved
  • Modifying device configuration parameters after firmware updates
  • Recording operational notes and maintenance information
  • Updating device user assignments and access permissions

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_operation/123/

Parameters:

Parameter Type In Required Description
id integer path Yes Unique identifier of the device to update
data string body Yes JSON payload containing the operational updates to apply to the device

cURL Example:

curl -X PUT "https://control.zequenze.com/api/v1/inventory_device_operation/123/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operational_status": "maintenance",
    "location": "Building A - Floor 2",
    "assigned_user": "john.doe@company.com",
    "maintenance_notes": "Scheduled firmware update completed",
    "configuration": {
      "network_profile": "production",
      "monitoring_enabled": true,
      "alert_level": "standard"
    },
    "next_maintenance": "2024-04-15T09:00:00Z"
  }'

Example Response:

{
  "id": 123,
  "device_name": "Network Switch - NS-001",
  "serial_number": "NS001-ABC123",
  "device_type": "network_switch",
  "operational_status": "maintenance",
  "location": "Building A - Floor 2",
  "assigned_user": "john.doe@company.com",
  "organization": "IT Infrastructure",
  "configuration": {
    "network_profile": "production",
    "monitoring_enabled": true,
    "alert_level": "standard",
    "firmware_version": "2.1.4"
  },
  "maintenance_notes": "Scheduled firmware update completed",
  "next_maintenance": "2024-04-15T09:00:00Z",
  "last_updated": "2024-01-15T14:30:00Z",
  "updated_by": "admin@company.com",
  "operational_history": [
    {
      "timestamp": "2024-01-15T14:30:00Z",
      "action": "status_change",
      "from_status": "active",
      "to_status": "maintenance",
      "performed_by": "admin@company.com"
    }
  ]
}

Response Codes:

Status Description
200 Success - Device operation updated successfully
400 Bad Request - Invalid data format or missing required fields
401 Unauthorized - Invalid or missing API token
404 Not Found - Device with specified ID does not exist
403 Forbidden - Insufficient permissions to modify this device
422 Unprocessable Entity - Validation errors in the request data

Common Use Cases

Use Case 1: Device Maintenance Workflow

When taking a device offline for maintenance, use the PUT endpoint to update the operational status to "maintenance", add maintenance notes, and schedule the next maintenance window. This ensures proper tracking of device availability and maintenance history.

Use Case 2: Device Relocation

When moving devices to new locations, update the location field and any associated configuration changes (such as network profiles or monitoring settings) that may be required for the new environment.

Use Case 3: User Assignment Changes

When employees change roles or leave the organization, use this endpoint to reassign devices to new users, update access permissions, and modify any user-specific configuration parameters.

Use Case 4: Configuration Management

After firmware updates or configuration changes, use this endpoint to record the new configuration state, update version information, and document any operational changes that result from the updates.

Use Case 5: Device Lifecycle Management

Track devices through their operational lifecycle by updating status from "active" to "maintenance" to "decommissioned", maintaining a complete audit trail of device operational history.

Best Practices

  • Validate data before submission: Ensure all required fields are included and data types match the expected format to avoid validation errors.

  • Use meaningful operational notes: Include detailed descriptions of changes, reasons for updates, and any relevant context that will help with future maintenance and troubleshooting.

  • Implement proper error handling: Always check response status codes and handle different error scenarios appropriately, especially for 404 (device not found) and 403 (permission denied) responses.

  • Track operational history: The API maintains an operational history for audit purposes. Use this information to understand device lifecycle patterns and maintenance trends.

  • Coordinate with monitoring systems: Status changes may affect monitoring and alerting systems. Ensure your operational procedures account for these dependencies.

  • Security considerations: Only update devices that your API token has permissions to modify. Device operations may trigger security audits, so ensure all changes are properly authorized and documented.

  • Batch operations: For multiple device updates, consider implementing retry logic and rate limiting to avoid overwhelming the API while maintaining data consistency.

Back to top