n8n AWX Node

An unofficial n8n integration node for Ansible AWX/Tower with enhanced type safety

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

• TypeScript interfaces for AWX Projects and Job Templates
• Type-safe API interactions for key operations
• Job Templates (launch/get/list)
• Jobs (monitor/list)
• Inventories (get/list)
• Projects (get/list/update)
• Workflows (launch/get/list)
• Secure credential management
• Automatic pagination
• Enhanced error handling

Installation

npm install n8n-nodes-awx

Type-Safe Implementation

This package features TypeScript interfaces for key AWX resources:

• IAwxJobTemplate - Type-safe job template operations
• IAwxProject - Type-safe project operations

All API responses for these resources are properly typed, making it easier to work with AWX data in your workflows.

Example Flows

Please refer to the docs for an example on how to use this.

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

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"
    }
  ]
}

Recent Changes (2025)

New Features (24/04/2025)

• Simplified Project Update Parameters: The AWX Tool node's project update action now only exposes 'Project ID' and 'Project Name' fields for updates. All other fields (such as SCM Type, SCM URL, and Credential) are now only shown for project creation.
• Agent-Driven Project Modification: The AI agent can modify any project field (name, SCM type, SCM URL, credential) if the user's intent is clear, even if those fields are not exposed in the update UI.
• Manual SCM/Credential Update Option: If you want to allow manual override for SCM/Credential during project update, you can re-enable those fields in the update action.

Timeout Feature (21/04/2025)

• Configurable Timeout: Both the classic AWX node and the AWX Tool node now support a timeout parameter (in seconds) for API calls.
• Usage: Set the timeout field in node parameters to control the maximum wait time for AWX API requests. If the request exceeds this duration, the node will return a timeout error.
• Applies to: All resource operations (jobs, job templates, inventories, projects, workflows) and both standard and tool nodes.
• Type Safety: Timeout is fully typed and validated in the node interface.

Node Structure and Naming (21/04/2025)

• Removed deprecated AI node: All references to AWXToolAi.node/awxAi have been removed. Only AWXTool.node (AI tool node) and Awx.node (standard AWX node) remain.
• Export Cleanup: AwxTest.node (test node) and its references were removed for a cleaner package.
• Explicit Export: Awx.node is now explicitly exported in nodes/index.ts to ensure classic AWX functionality is available.

Build & Deployment (20/04/2025)

• Clean Build Process: Always remove dist, node_modules, and any old package in .n8n/nodes/node_modules/n8n-nodes-awx before building and deploying. See below for recommended commands.
• Deployment Structure: After building, copy the entire dist directory (not just nodes) and package.json to the n8n custom nodes directory so paths match your package.json.

Tool vs. Node (20/04/2025)

• Tool Nodes: Nodes like AWXTool.node are designed for AI/LLM agent workflows (set usableAsTool: true and list in the tools array in package.json).
• Classic Nodes: Nodes like Awx.node are for standard n8n workflow building and are listed in the nodes array.

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.