n8n AWX Node

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.

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

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

npm install n8n-nodes-awx

Usage Examples

Launch Job Template with Variables

{
  "resource": "jobTemplate",
  "action": "launch",
  "parameters": {
    "jobTemplateName": "Web Server Deployment",
    "inventoryName": "Production Servers",
    "extraVariables": {
      "limit": "web",
      "tags": "deploy"
    }
  }
}

Manage Project with SCM Integration

{
  "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

{
  "resource": "jobs",
  "action": "list",
  "parameters": {
    "createdAfter": "last week",
    "returnAll": true,
    "format": "ai_friendly"
  }
}

Using JSON Transformer with Natural Language

{
  "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

{
  "resource": "jobs",
  "action": "get",
  "id": "123",
  "responseFormat": "friendly"
}

AI Integration

Natural Language Queries

{
  "resource": "jobs",
  "action": "list",
  "parameters": {
    "status": "failed",
    "createdAfter": "yesterday"
  }
}

Resource Resolution

Resources can be referenced by name or ID, with automatic resolution:

{
  "resource": "host",
  "action": "get",
  "parameters": {
    "inventoryName": "Production",
    "hostName": "web-server-01"
  }
}

{
  "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

{
  "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

{
  "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

{
  "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)

{
  "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

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:

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 file for details.

Support

For issues and feature requests, please use the GitHub Issues page.

{
  "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:

// 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

Natural Language Filter Example

{
  "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

{
  "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

API Documentation

• AWX REST API Reference
• n8n Nodes Documentation

Example with Inventory Selection

{
  "parameters": {
    "operation": "launch",
    "jobTemplateId": "1",
    "inventoryId": "2",
    "extraVariables": "{\"target\":\"production\"}"
  }
}

Workflow with Approval Step

{
  "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

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

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.