335 lines
10 KiB
Markdown
335 lines
10 KiB
Markdown
# API Integration Documentation
|
|
|
|
## Overview
|
|
|
|
The PowerShell scripts integrate with a centralized Dashboard API to store comprehensive asset data in a MySQL database. This document details the API communication protocols, data structures, and integration patterns.
|
|
|
|
## Dashboard API Architecture
|
|
|
|
### Base URL Structure
|
|
```
|
|
Primary: http://10.48.130.197/dashboard-v2/api.php
|
|
Fallback: http://localhost/dashboard-v2/api.php
|
|
Test: http://10.48.130.197/test/dashboard/api.php
|
|
```
|
|
|
|
### Auto-Discovery Mechanism
|
|
```powershell
|
|
function Get-DashboardURL {
|
|
# Priority order:
|
|
# 1. Command-line parameter
|
|
# 2. Environment variable (ASSET_DASHBOARD_URL)
|
|
# 3. Configuration file (dashboard-config.json)
|
|
# 4. Auto-discovery probe
|
|
# 5. Default fallback
|
|
}
|
|
```
|
|
|
|
## API Endpoint: `updateCompleteAsset`
|
|
|
|
### Request Structure
|
|
```http
|
|
POST /dashboard-v2/api.php HTTP/1.1
|
|
Content-Type: application/x-www-form-urlencoded
|
|
|
|
action=updateCompleteAsset&hostname=H123EXAMPLE&serialNumber=ABC123&...
|
|
```
|
|
|
|
### Complete Payload Structure
|
|
|
|
#### Core System Information
|
|
```powershell
|
|
$postData = @{
|
|
action = 'updateCompleteAsset'
|
|
|
|
# Basic System Identification
|
|
hostname = $SystemInfo.Hostname # String: Computer name
|
|
serialNumber = $SystemInfo.SerialNumber # String: Hardware serial
|
|
serviceTag = $SystemInfo.ServiceTag # String: Dell service tag
|
|
manufacturer = $SystemInfo.Manufacturer # String: Dell, HP, etc.
|
|
model = $SystemInfo.Model # String: OptiPlex 7070, etc.
|
|
|
|
# System Classification & Context
|
|
pcType = $SystemInfo.PCType # String: Engineer|Shopfloor|Standard
|
|
loggedInUser = $SystemInfo.LoggedInUser # String: Current user
|
|
machineNo = $SystemInfo.MachineNo # String: M123 (GE machine number)
|
|
|
|
# Technical Specifications
|
|
osVersion = $SystemInfo.OSVersion # String: Windows 10, etc.
|
|
totalPhysicalMemory = $SystemInfo.TotalPhysicalMemory # Decimal: GB
|
|
domainRole = $SystemInfo.DomainRole # Integer: Domain membership
|
|
currentTimeZone = $SystemInfo.CurrentTimeZone # String: Timezone ID
|
|
lastBootUpTime = $SystemInfo.LastBootUpTime # DateTime: Last boot
|
|
}
|
|
```
|
|
|
|
#### Manufacturing-Specific Data (Shopfloor PCs Only)
|
|
```powershell
|
|
# Network Interface Data (JSON Array)
|
|
$postData.networkInterfaces = [
|
|
{
|
|
"InterfaceName": "Ethernet 2",
|
|
"IPAddress": "192.168.1.100",
|
|
"SubnetMask": 24,
|
|
"DefaultGateway": "192.168.1.1",
|
|
"MACAddress": "00-15-5D-A2-33-4F",
|
|
"IsDHCP": 0,
|
|
"IsActive": 1,
|
|
"IsMachineNetwork": 1
|
|
}
|
|
] | ConvertTo-Json -Compress
|
|
|
|
# Communication Configuration Data (JSON Array)
|
|
$postData.commConfigs = [
|
|
{
|
|
"PortName": "COM1",
|
|
"BaudRate": 9600,
|
|
"DataBits": 8,
|
|
"Parity": "None",
|
|
"StopBits": 1,
|
|
"IsActive": 1
|
|
}
|
|
] | ConvertTo-Json -Compress
|
|
|
|
# DNC Configuration Data (JSON Object)
|
|
$postData.dncConfig = {
|
|
"Site": "WestJefferson",
|
|
"CNC": "Fanuc 30",
|
|
"NcIF": "EFOCAS",
|
|
"MachineNo": "3109",
|
|
"Debug": "ON",
|
|
"HostType": "WILM"
|
|
} | ConvertTo-Json -Compress
|
|
```
|
|
|
|
#### GE Registry Architecture Data **New in v3.0**
|
|
```powershell
|
|
# DualPath Communication Settings
|
|
$postData.dncDualPathEnabled = $true # Boolean: DualPath enabled
|
|
$postData.dncPath1Name = "Path1Primary" # String: Primary path name
|
|
$postData.dncPath2Name = "Path2Secondary" # String: Secondary path name
|
|
|
|
# Registry Architecture Detection
|
|
$postData.dncGeRegistry32Bit = $true # Boolean: Found in 32-bit registry
|
|
$postData.dncGeRegistry64Bit = $false # Boolean: Found in 64-bit registry
|
|
|
|
# Additional Registry Metadata (JSON Object)
|
|
$postData.dncGeRegistryNotes = {
|
|
"32bit": {
|
|
"BasePath": "HKLM:\\SOFTWARE\\GE Aircraft Engines",
|
|
"SubKeys": "DNC, Enhanced DNC, MarkZebra, PPDCS",
|
|
"Found": "2025-09-06 14:30:00"
|
|
},
|
|
"32bit-eFocas": {
|
|
"DualPath": "YES",
|
|
"Path1Name": "Path1Primary",
|
|
"Path2Name": "Path2Secondary",
|
|
"IpAddr": "192.168.1.1",
|
|
"SocketNo": "8192"
|
|
}
|
|
} | ConvertTo-Json -Compress
|
|
```
|
|
|
|
#### Warranty Information (Dell Systems Only)
|
|
```powershell
|
|
# Currently disabled but structure available
|
|
$postData.warrantyEndDate = $WarrantyData.warrantyEndDate # Date: YYYY-MM-DD
|
|
$postData.warrantyStatus = $WarrantyData.warrantyStatus # String: Active|Expired
|
|
$postData.warrantyServiceLevel = $WarrantyData.serviceLevel # String: Service level
|
|
$postData.warrantyDaysRemaining = $WarrantyData.daysRemaining # Integer: Days remaining
|
|
```
|
|
|
|
## API Response Handling
|
|
|
|
### Success Response Structure
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"success": true,
|
|
"message": "Complete asset data updated successfully",
|
|
"pcid": 221,
|
|
"hostname": "H123EXAMPLE",
|
|
"operation": "complete_asset_update",
|
|
"recordsAffected": 3,
|
|
"pcType": "Shopfloor",
|
|
"warrantyStatus": null,
|
|
"machineNo": "M123",
|
|
"timestamp": "2025-09-06 14:30:45",
|
|
"debugMsg": "PCType=Shopfloor, DNC=YES, Net=YES"
|
|
},
|
|
"timestamp": "2025-09-06 14:30:45"
|
|
}
|
|
```
|
|
|
|
### Error Response Structure
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "hostname and serial number are required",
|
|
"timestamp": "2025-09-06 14:30:45"
|
|
}
|
|
```
|
|
|
|
### Response Processing Logic
|
|
```powershell
|
|
$response = Invoke-RestMethod -Uri $DashboardURL -Method Post -Body $postData -Headers $headers -TimeoutSec 30
|
|
|
|
if ($response.success) {
|
|
Write-Host "[OK] Complete asset data stored in database!" -ForegroundColor Green
|
|
$data = $response.data
|
|
Write-Host " PCID: $($data.pcid)"
|
|
Write-Host " Operation: $($data.operation)"
|
|
Write-Host " Records affected: $($data.recordsAffected)"
|
|
return $true
|
|
} else {
|
|
Write-Host "[FAIL] Dashboard could not store data: $($response.error)" -ForegroundColor Red
|
|
return $false
|
|
}
|
|
```
|
|
|
|
## Database Schema Integration
|
|
|
|
### Primary Tables Updated
|
|
|
|
#### `pc` Table (Core System Information)
|
|
```sql
|
|
UPDATE pc SET
|
|
hostname = ?, serialnumber = ?, modelnumberid = ?,
|
|
pctypeid = ?, loggedinuser = ?, machinenumber = ?,
|
|
operatingsystem = ?, warrantyenddate = ?, warrantystatus = ?,
|
|
warrantyservicelevel = ?, warrantydaysremaining = ?,
|
|
warrantylastchecked = IF(? IS NOT NULL, NOW(), warrantylastchecked),
|
|
lastupdated = NOW()
|
|
WHERE pcid = ?
|
|
```
|
|
|
|
#### `pc_dnc_config` Table (Manufacturing Configuration) **Enhanced in v3.0**
|
|
```sql
|
|
INSERT INTO pc_dnc_config (
|
|
pcid, site, cnc, ncif, machinenumber, hosttype,
|
|
ftphostprimary, ftphostsecondary, ftpaccount,
|
|
debug, uploads, scanner, dripfeed, additionalsettings,
|
|
dualpath_enabled, path1_name, path2_name, -- DualPath settings
|
|
ge_registry_32bit, ge_registry_64bit, ge_registry_notes, -- Registry architecture
|
|
lastupdated
|
|
) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NOW())
|
|
ON DUPLICATE KEY UPDATE ...
|
|
```
|
|
|
|
#### `machines` Table (Auto-Population) **New in v3.2**
|
|
```sql
|
|
-- Machine records created from PC data
|
|
INSERT INTO machines (
|
|
machinenumber, alias, machinetypeid, isactive,
|
|
businessunitid, modelnumberid, printerid,
|
|
ipaddress1, machinenotes
|
|
)
|
|
SELECT DISTINCT
|
|
p.machinenumber,
|
|
CONCAT('Machine ', p.machinenumber),
|
|
1, 1, 1, 1, 1,
|
|
ni.ipaddress,
|
|
CONCAT('Auto-discovered | Connected PCs: ', GROUP_CONCAT(p.hostname))
|
|
FROM pc p
|
|
LEFT JOIN pc_network_interfaces ni ON p.pcid = ni.pcid
|
|
WHERE p.machinenumber IS NOT NULL
|
|
GROUP BY p.machinenumber;
|
|
|
|
-- PC-Machine relationship tracking
|
|
INSERT INTO machine_pc_relationships (
|
|
machine_id, pc_id, pc_hostname, pc_role, is_primary
|
|
)
|
|
SELECT
|
|
m.machineid, p.pcid, p.hostname,
|
|
CASE
|
|
WHEN p.hostname LIKE '%HMI%' THEN 'hmi'
|
|
WHEN p.hostname LIKE '%CONTROL%' THEN 'control'
|
|
ELSE 'unknown'
|
|
END,
|
|
(p.lastupdated = MAX(p.lastupdated) OVER (PARTITION BY p.machinenumber))
|
|
FROM machines m
|
|
JOIN pc p ON m.machinenumber = p.machinenumber;
|
|
```
|
|
|
|
## Connection Management
|
|
|
|
### URL Auto-Discovery Process
|
|
```powershell
|
|
# Test candidate URLs in priority order
|
|
$candidates = @(
|
|
"http://10.48.130.197/dashboard-v2/api.php", # Production primary
|
|
"http://10.48.130.197/test/dashboard/api.php", # Test environment
|
|
"http://localhost/dashboard-v2/api.php" # Local development
|
|
)
|
|
|
|
foreach ($url in $candidates) {
|
|
$testResponse = Invoke-RestMethod -Uri "$url?action=getDashboardData" -Method Get -TimeoutSec 5
|
|
if ($testResponse.success) {
|
|
return $url # First successful connection wins
|
|
}
|
|
}
|
|
```
|
|
|
|
### Error Handling & Retries
|
|
```powershell
|
|
# HTTP timeout and error handling
|
|
try {
|
|
$response = Invoke-RestMethod -Uri $DashboardURL -Method Post -Body $postData -Headers $headers -TimeoutSec 30
|
|
}
|
|
catch [System.Net.WebException] {
|
|
Write-Host "[FAIL] Network error: $($_.Exception.Message)" -ForegroundColor Red
|
|
return $false
|
|
}
|
|
catch {
|
|
Write-Host "[FAIL] Unexpected error: $($_.Exception.Message)" -ForegroundColor Red
|
|
return $false
|
|
}
|
|
```
|
|
|
|
## Data Validation & Integrity
|
|
|
|
### Required Fields Validation
|
|
```powershell
|
|
# API enforces required fields
|
|
if (empty($hostname) || empty($serialnumber)) {
|
|
$this->sendError('hostname and serial number are required');
|
|
return;
|
|
}
|
|
```
|
|
|
|
### Data Type Conversion
|
|
```powershell
|
|
# Boolean conversion for registry flags
|
|
$dncDualPathEnabled = isset($_POST['dncDualPathEnabled']) ?
|
|
(($_POST['dncDualPathEnabled'] === 'true' || $_POST['dncDualPathEnabled'] === '1' ||
|
|
$_POST['dncDualPathEnabled'] === 1 || $_POST['dncDualPathEnabled'] === true) ? 1 : 0) : null;
|
|
```
|
|
|
|
### JSON Serialization
|
|
```powershell
|
|
# Complex objects serialized as JSON
|
|
$postData.networkInterfaces = $ShopfloorInfo.NetworkInterfaces | ConvertTo-Json -Compress
|
|
$postData.dncGeRegistryNotes = $geInfo.RegistryNotes | ConvertTo-Json -Compress
|
|
```
|
|
|
|
## Performance Optimization
|
|
|
|
### Payload Compression
|
|
- JSON objects compressed with `-Compress` flag
|
|
- Minimal redundant data transmission
|
|
- Efficient HTTP POST encoding
|
|
|
|
### Connection Pooling
|
|
- Reuses HTTP connections where possible
|
|
- Configurable timeout values
|
|
- Graceful connection cleanup
|
|
|
|
### Batch Processing Capability
|
|
- Single API call handles complete asset profile
|
|
- Atomic database transactions
|
|
- Rollback capability on failures
|
|
|
|
---
|
|
|
|
**API Integration designed for reliable, efficient, and comprehensive asset data management in enterprise manufacturing environments.** |