n8n-nodes-arubacentral/dist/nodes/ArubaCentral/docs/PROMPT_Monitoring.md

n8n community node for Aruba Central API integration with comprehensive monitoring, configuration, and management capabilities

# Aruba Central API Node for n8n: Development & Troubleshooting Guide

You're working on an n8n integration node for Aruba Central API. This comprehensive guide will help you continue development, implement new features, and troubleshoot issues with the codebase.

## Project Structure

```
.
├── arubaCentral.svg                        # Node icon
├── credentials
│   └── ArubaCentralOAuth2Api.credentials.ts # OAuth2 credential handling
├── descriptions
│   ├── baseProperties.ts                   # Base UI descriptions
│   ├── firmware.descriptions.ts
│   └── monitoring.descriptions.ts          # UI elements for monitoring domain
├── helpers
│   ├── apiRequest.ts                       # API request handling with OAuth2
│   ├── errorHandler.ts                     # Error handling utilities
│   ├── executeOperation.ts                 # Routes operations to appropriate handlers
│   ├── pagination.ts
│   └── responseFormatter.ts                # Formats API responses for n8n
├── index.ts                                # Main node entry point
├── methods
│   ├── firmware
│   │   ├── compliance
│   │   │   └── compliance.methods.ts
│   │   ├── devices
│   │   │   └── devices.methods.ts
│   │   ├── status
│   │   │   └── status.methods.ts
│   │   ├── upgrades
│   │   │   └── upgrades.methods.ts
│   │   └── versions
│   │       └── versions.methods.ts
│   └── monitoring                          # API domain: monitoring
│       ├── ap                              # Access Point operations
│       │   └── ap.methods.ts
│       ├── clients                         # Client operations
│       │   └── clients.methods.ts
│       ├── labels                          # Label operations
│       │   └── labels.methods.ts
│       ├── sites                           # Site operations
│       │   └── sites.methods.ts
│       └── switch                          # Switch operations
│           └── switch.methods.ts
└── types
    ├── common.types.ts                     # Common TypeScript interfaces
    ├── firmware.types.ts
    └── monitoring.types.ts                 # Monitoring-specific interfaces
```

## Architecture & Design Pattern

The node follows a modular design pattern that separates:

1. **UI Descriptions**: Define the user interface elements in `descriptions/*.ts`
2. **Method Implementation**: Business logic grouped by resource in `methods/*/*/*.methods.ts`
3. **Operation Routing**: Central handler that maps domain/resource/operation to implementation in `executeOperation.ts`
4. **Type Definitions**: TypeScript interfaces in `types/*.ts`
5. **API Communication**: Consolidated in `apiRequest.ts` with OAuth2 handling

### Operation Flow

1. User selects Domain → Resource → Operation in n8n UI
2. `index.ts` handles the execution and calls `executeOperation.ts`
3. `executeOperation.ts` maps to the appropriate method handler
4. Method handler uses `apiRequest.ts` to call Aruba Central API
5. Response is formatted with `responseFormatter.ts` and returned to n8n

## Adding New API Operations

To add a new operation, follow these steps:

1. **Update Type Definitions**: Add any new interfaces to appropriate `types/*.ts` file
2. **Implement Method**: Create or update a method in appropriate `methods/*/*/*.methods.ts` file
3. **Update UI Descriptions**: Add UI elements in appropriate `descriptions/*.ts` file
4. **Register in Operation Handler**: Add method to the handlers object in `executeOperation.ts`

### Example: Adding a New API Endpoint

For example, to add "Get Device Status" to monitoring domain:

1. Add interfaces to `monitoring.types.ts`:
```typescript
export interface DeviceStatus {
  serial?: string;
  status?: string;
  last_updated?: number;
  // other properties
}
```

2. Create method implementation:
```typescript
// methods/monitoring/devices/devices.methods.ts
export async function getDeviceStatus(this: IExecuteFunctions): Promise<INodeExecutionData[]> {
  try {
    const serial = this.getNodeParameter('serial', 0) as string;
    const endpoint = `/monitoring/v1/devices/${serial}/status`;
    const response = await apiRequest.call(this, 'GET', endpoint, {}, {});
    return formatResponse(response);
  } catch (error) {
    console.log('ERROR in getDeviceStatus:', error);
    throw error;
  }
}
```

3. Update descriptions:
```typescript
// Update in monitoring.descriptions.ts
export const deviceOperations: INodeProperties = {
  // ... existing code
  options: [
    // ... existing options
    {
      name: 'Get Device Status',
      value: 'getStatus',
      description: 'Get status of a device',
      action: 'Get device status',
    },
  ],
};

// Add fields for the operation
export const deviceFields: INodeProperties[] = [
  // ... existing fields
  {
    displayName: 'Serial Number',
    name: 'serial',
    type: 'string',
    required: true,
    default: '',
    description: 'Serial number of the device',
    displayOptions: {
      show: {
        domain: ['monitoring'],
        resource: ['devices'],
        operation: ['getStatus'],
      },
    },
  },
];
```

4. Update operation handler:
```typescript
// In executeOperation.ts
import { getDeviceStatus } from '../methods/monitoring/devices/devices.methods';

// Inside handlers object
devices: {
  // ... existing operations
  getStatus: getDeviceStatus,
},
```

## Troubleshooting

### Common Issues

1. **TypeScript Build Errors**
   - Check type definitions match API responses
   - Ensure consistent typing between parameters and usage
   - Fix comparison issues (e.g., `if (number !== '')` should be `if (number !== undefined)`)

2. **API Authentication Errors (401)**
   - Verify credentials in n8n UI
   - Check OAuth2 implementation in `ArubaCentralOAuth2Api.credentials.ts`
   - Ensure token refresh is working properly

3. **Bad Requests (400)**
   - Log request payload and query parameters
   - Compare against API documentation
   - Check if required parameters are missing or malformed

4. **Missing UI Elements**
   - Ensure operations are registered in `monitoring.descriptions.ts`
   - Verify operations are exported in both descriptions and methods files
   - Check that operations are properly registered in `executeOperation.ts`

5. **Syntax Errors**
   - Look for missing brackets/braces, especially in long arrays/objects
   - Check for duplicate declarations (e.g., redefining same variable)
   - Verify proper semicolons and commas

### Debugging Tips

1. Use extensive logging with `console.log()` statements before/after key operations
2. Log API request details before sending: URL, method, headers, body
3. Log responses from API calls to identify unexpected formats
4. Implement proper error handling to catch and log specific issues

## OAuth2 Authentication

The node uses OAuth2 authentication implemented in `ArubaCentralOAuth2Api.credentials.ts` and used in `apiRequest.ts`. The authentication flow includes:

1. Initial auth with client credentials or password grant
2. Token storage and caching
3. Automatic token refresh when expired
4. Session handling for API requests

## Best Practices

1. **Consistent Error Handling**: Use try-catch in all methods with proper logging
2. **Parameter Validation**: Check parameters before making API requests
3. **Documentation**: Add comments for complex logic
4. **Testing**: Test operations with various parameter combinations
5. **Code Organization**: Follow the established pattern of domain/resource/operation 

## Next Steps for Development

Your task is to implement the remaining resources for the monitoring domain:

**Monitoring Domain**
   - Events endpoint with all available parameters (/monitoring/v2/events)
   - Clients endpoint, ensure list unified clients actions work correctly

## API Documentation References

For more details on available endpoints and parameters, refer to the Aruba Central API documentation. New operations should follow the existing pattern while ensuring alignment with the official API specifications.