Initial commit: Organized PowerShell scripts for ShopDB asset collection
Structure: - asset-collection/: Local PC data collection scripts - remote-execution/: WinRM remote execution scripts - setup-utilities/: Configuration and testing utilities - registry-backup/: GE registry backup scripts - winrm-https/: WinRM HTTPS certificate setup - docs/: Complete documentation Each folder includes a README with detailed documentation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
cproudlock
335
docs/API_INTEGRATION.md
Normal file
335
docs/API_INTEGRATION.md
Normal file
@@ -0,0 +1,335 @@
|
||||
# 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.**
|
||||
Reference in New Issue
Block a user