n8n-nodes-awx/README.md

n8n node to interact with Ansible AWX/Tower with improved type safety

# n8n AWX Node

<p align="center">
  <img src="https://raw.githubusercontent.com/ansible/awx-logos/master/awx/ui/client/assets/logo-header.svg" width="400" alt="Ansible AWX Logo">
</p>

*An unofficial n8n integration node for Ansible AWX/Tower with enhanced type safety and AI support*

**Trademark Notice**: Ansible®, AWX®, and Red Hat® are trademarks of Red Hat, Inc. This project is not affiliated with or endorsed by Red Hat.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Version](https://img.shields.io/npm/v/n8n-nodes-awx.svg)](https://www.npmjs.com/package/n8n-nodes-awx)
[![Downloads](https://img.shields.io/npm/dm/n8n-nodes-awx.svg)](https://www.npmjs.com/package/n8n-nodes-awx)

## Features

### Core Functionality
- Complete TypeScript support with strict type checking
- Full CRUD operations for all major AWX resources
- Support for both AWX and Red Hat Ansible Automation Platform
- Comprehensive error handling and logging
- Automatic pagination for list operations
- Secure credential management
- Built-in retry logic for failed requests

### Supported Resources
- **Job Templates** - Launch, get, list, and manage job templates
- **Jobs** - Monitor job status, view output, and manage job execution
- **Workflow Job Templates** - Launch and manage workflow jobs
- **Inventories** - Manage inventory sources, groups, and hosts
- **Projects** - Full CRUD operations with SCM integration and updates
- **Hosts & Groups** - Full CRUD operations with inventory relationships
- **Workflow Jobs** - Comprehensive workflow job management

### AI & Automation
- **JSON Transformer Architecture** - Convert natural language to structured API calls
- AI-friendly parameter names for natural language processing
- Smart resource resolution by name or ID with fallback mechanisms
- Built-in support for AI agent integration with specific parameter rules
- Natural language date filtering (e.g., "last week", "in April")
- Automated URL generation for web UI access
- Consistent response formats for AI processing

## Installation
```bash
npm install n8n-nodes-awx
```

## Type-Safe Implementation
This package features comprehensive TypeScript interfaces for all AWX resources:
- `IAwxJobTemplate` - Type-safe job template operations
- `IAwxProject` - Type-safe project operations with SCM integration
- `IAwxInventory` - Type-safe inventory management
- `IAwxHost` & `IAwxGroup` - Type-safe host and group operations
- `IAwxWorkflowJob` - Type-safe workflow job handling

All API responses are properly typed, ensuring type safety throughout your n8n workflows.

## Getting Started

### Prerequisites
- Node.js 18 or later
- n8n 1.0.0 or later
- Ansible AWX or Red Hat Ansible Automation Platform

### Installation
```bash
npm install n8n-nodes-awx
```

## Usage Examples

### Launch Job Template with Variables
```json
{
  "resource": "jobTemplate",
  "action": "launch",
  "parameters": {
    "jobTemplateName": "Web Server Deployment",
    "inventoryName": "Production Servers",
    "extraVariables": {
      "limit": "web",
      "tags": "deploy"
    }
  }
}
```

### Manage Project with SCM Integration
```json
{
  "resource": "project",
  "action": "update",
  "parameters": {
    "name": "Ansible Playbooks",
    "scmType": "git",
    "scmUrl": "https://github.com/username/ansible-playbooks.git",
    "scmBranch": "main",
    "updateOnLaunch": true
  }
}
```

### List All Jobs from Last Week with AI-Friendly Query
```json
{
  "resource": "jobs",
  "action": "list",
  "parameters": {
    "createdAfter": "last week",
    "returnAll": true,
    "format": "ai_friendly"
  }
}
```

### Using JSON Transformer with Natural Language
```json
{
  "text": "Show me all failed jobs from the last 3 days",
  "transformType": "job_list"
}
```

### Full Workflow with Monitoring

## Advanced Features

### Job Output Handling
- The `jobs` resource `get` action returns job output in different formats based on the `responseFormat` parameter:
  - `friendly`: Includes `job_output` as plain text
  - `minimal`: Basic job metadata only
  - `full` (default): Complete job details with optional output

#### Example: Get Job with Friendly Format
```json
{
  "resource": "jobs",
  "action": "get",
  "id": "123",
  "responseFormat": "friendly"
}
```

### AI Integration

#### Natural Language Queries
```json
{
  "resource": "jobs",
  "action": "list",
  "parameters": {
    "status": "failed",
    "createdAfter": "yesterday"
  }
}
```

#### Resource Resolution
Resources can be referenced by name or ID, with automatic resolution:
```json
{
  "resource": "host",
  "action": "get",
  "parameters": {
    "inventoryName": "Production",
    "hostName": "web-server-01"
  }
}
```

```json
{
  "nodes": [
    {
      "parameters": {
        "operation": "launch",
        "jobTemplateId": "1"
      },
      "name": "Launch Job"
    },
    {
      "parameters": {
        "operation": "get",
        "resource": "jobs",
        "id": "={{ $node['Launch Job'].json.id }}"
      },
      "name": "Monitor Job",
      "executeOnce": false,
      "maxExecutions": 10
    }
  ]
}
```

### 4. Error Handling Example
```json
{
  "nodes": [
    {
      "parameters": {
        "operation": "launch",
        "jobTemplateId": "1"
      },
      "name": "Launch Job",
      "continueOnFail": true
    },
    {
      "parameters": {
        "if": "={{ $node['Launch Job'].json.failed === true }}",
        "message": "Job failed: {{ $node['Launch Job'].json.msg }}"
      },
      "type": "n8n-nodes-base.if"
    }
  ]
}
```

### Launch Job by Template ID
```json
{
  "nodes": [
    {
      "parameters": {
        "operation": "launch",
        "jobTemplateId": "1",
        "extraVariables": "{\"debug\":true}"
      },
      "name": "Launch AWX Job",
      "type": "n8n-nodes-awx.awx",
      "typeVersion": 1
    }
  ]
}
```

### Launch Job by Template Name
```json
{
  "nodes": [
    {
      "parameters": {
        "operation": "list",
        "resource": "jobTemplates",
        "filter": "name:My Template Name"
      },
      "name": "Get Template ID",
      "type": "n8n-nodes-awx.awx",
      "typeVersion": 1
    },
    {
      "parameters": {
        "operation": "launch",
        "jobTemplateId": "={{ $node[\"Get Template ID\"].json.results[0].id }}",
        "extraVariables": ""
      },
      "name": "Launch Job",
      "type": "n8n-nodes-awx.awx",
      "typeVersion": 1
    }
  ]
}
```

### Inventory Selection (AI Pattern)
```json
{
  "resource": "job",
  "action": "launch",
  "parameters": {
    "jobTemplateName": "Database Maintenance",
    "inventoryName": "Production Servers",  // AI: Uses natural language name
    "extraVariables": {
      "target": "production"
    }
  }
}
```

## Best Practices

### Parameter Naming
Use these parameter names for consistency and AI compatibility:

| Resource Type | ID Parameter | Name Parameter |
|--------------|-------------|----------------|
| Job Template | `jobTemplateId` | `jobTemplateName` |
| Inventory | `inventoryId` | `inventoryName` |
| Host | `hostId` | `hostName` |
| Group | `groupId` | `groupName` |
| Project | `projectId` | `projectName` |

### Error Handling
- Always check the `failed` flag in responses
- Use `continueOnFail` for non-critical operations
- Implement retry logic for transient failures

## Development

### Building from Source
```bash
git clone https://github.com/your-org/n8n-nodes-awx.git
cd n8n-nodes-awx
npm install
npm run build
```

### Testing
Run the test suite with:
```bash
npm test
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a new Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

For issues and feature requests, please use the [GitHub Issues](https://github.com/your-org/n8n-nodes-awx/issues) page.

```json
{
  "resource": "jobTemplate",
  "action": "launch",
  "Job_Template_ID": "42"
}
```

### Error Cases
If both parameters are provided, `Job_Template_ID` will be prioritized
If neither parameter is provided, an error will be returned:
`Error: Either Job Template ID or Name must be provided`

## Filtering Resources

When listing resources in the n8n UI, you can filter using simple field inputs. These are automatically converted to the proper AWX API syntax:

### UI Filter Fields
- **Name**: Simple text input (matches partial names)
- **Organization**: Dropdown or text input
- **Status**: Dropdown selection

### Underlying API Syntax
For reference, these UI filters translate to:
1. **Name**
   - UI input becomes: `name__contains=your_search_term`
2. **Organization**
   - UI selection becomes: `organization__name__contains=org_name` or `organization=id`
3. **Status**
   - UI selection becomes: `status=selected_status`

For advanced filtering needs (like exact matches or case-insensitive search), you'll need to modify the node code or use direct API calls.

### Advanced Filter Patterns

You can combine multiple filters using AND conditions:

```javascript
// Multiple filters
name:MyTemplate AND organization:Default AND status:running

// Date ranges
created__gte:2025-01-01 AND created__lte:2025-12-31

// Numeric comparisons
id__gt:100 AND id__lt:200
```

For full syntax details, see the [AWX API Filtering Documentation](https://docs.ansible.com/automation-controller/latest/html/userguide/api.html#filtering)

### Natural Language Filter Example
```json
{
  "resource": "host",
  "action": "list",
  "filters": {
    "text": "web servers in datacenter A deployed after January 2025"
  }
}
```

## Recent Changes

### Standardized Response Formats
All Group and Host operations now return data in a consistent format:
- `list` operations return arrays of items
- `get` operations return single items
- Responses are wrapped in n8n's INodeExecutionData structure

### Required Parameters
- All host/group operations now require `inventoryName` or `inventoryId`
- Host operations require either `hostName` or `hostId`
- Group operations require either `groupName` or `groupId`

### Example Usage
```json
{
  "resource": "host",
  "action": "get",
  "inventoryName": "Production",
  "hostName": "web-server-01"
}
```

## Internal Improvements

- Refactored internal file structure for better maintainability
- Rewrote test suite with 100% coverage for core operations

## Additional Resources

### Node Configuration Screenshot
![AWX Node Configuration](https://example.com/path/to/screenshot.png)

### API Documentation
- [AWX REST API Reference](https://docs.ansible.com/automation-controller/latest/html/userguide/api.html)
- [n8n Nodes Documentation](https://docs.n8n.io/integrations/)

### Example with Inventory Selection
```json
{
  "parameters": {
    "operation": "launch",
    "jobTemplateId": "1",
    "inventoryId": "2",
    "extraVariables": "{\"target\":\"production\"}"
  }
}
```

### Workflow with Approval Step
```json
{
  "nodes": [
    {
      "parameters": {
        "operation": "launch",
        "jobTemplateId": "1"
      },
      "name": "Launch Job"
    },
    {
      "parameters": {
        "type": "approval",
        "message": "Approve production deployment?"
      },
      "name": "Approval Step",
      "type": "n8n-nodes-base.manual"
    },
    {
      "parameters": {
        "operation": "get",
        "resource": "jobs",
        "id": "={{ $node['Launch Job'].json.id }}"
      },
      "name": "Monitor Job"
    }
  ]
}
```

## Version History
For detailed release notes and changes, see:  
[CHANGELOG.md](docs/CHANGELOG.md)

## Configuration
1. Add "AWX API" credentials in n8n
2. Set:
   - Base URL (e.g., `https://your-awx-instance.com`)
   - API Token

## Troubleshooting
- **Connection issues**: Verify base URL ends with `/api/v2` for AWX
- **Authentication errors**: Regenerate API token in AWX
- **Version Support**: Compatible with AWX 15+ and n8n 1.0+

## Development
```bash
npm install
npm run build
```

***

## Authors and License

**Author**: Wei-Yen Tan

**License**: MIT License

```
Copyright (c) 2025 Wei-Yen Tan

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.