n8n-nodes-autotask v0.3.1

n8n-nodes-autotask

This is an n8n community node for integrating with Autotask PSA. It provides a comprehensive set of operations to interact with Autotask entities through their REST API.

n8n is a fair-code licensed workflow automation platform.

Installation
Authentication
Features
Usage
Configuration
Limitations
Troubleshooting
Resources
License

Installation

Follow these steps to install this node:

# Install with npm
npm install n8n-nodes-autotask

# Install with pnpm
pnpm install n8n-nodes-autotask

Requirements:

• n8n version 1.0.0 or later
• Node.js version 18.10 or later
• pnpm version 9.1 or later (if using pnpm)

Authentication

To use this node, you need to have API access to your Autotask instance. Follow these steps to set up authentication:

1. In Autotask, go to Admin > API User Security
2. Create or select an API user
3. Note the API Integration Code, Username, and Secret
4. In n8n, create a new credential of type Autotask API
5. Enter your API Integration Code, Username, and Secret
6. Select your Autotask zone
7. Select your timezone (affects how dates and times are displayed and entered)
8. Configure caching options as needed (this will cache dynamically fetched field picklists)

Features

Supported Resources

The node supports the following Autotask resources:

Operations

For most resources, the following operations are available:

• Create: Add new records
• Read: Retrieve a single record by ID
• Update: Modify existing records
• Delete: Remove records
• Get Many: Retrieve multiple records with basic filtering options. This operation allows you to:
  • Filter records using simple field conditions (equals)
  • Filtering on User Defined Fields (UDFs)
  • Automatically paginate through large result sets
  • Choose to get all results or limit to a specific number (1-500)
  • Set a maximum number of records to return when not retrieving all records
• Get Many Advanced: Build complex queries with multiple filter conditions and logical operators. This operation provides:
  • Support for complex AND/OR logic in filters
  • Nested condition groups for sophisticated queries
  • Filtering on User Defined Fields (UDFs)
  • Advanced operators like contains, beginsWith, endsWith, exists, notExists
  • Support for IN and NOT IN operators with multiple values
  • Choose to get all results or limit to a specific number (1-500)
  • Set a maximum number of records to return when not retrieving all records
• Count: Get the number of matching records
• Get Entity Info: Retrieve metadata about the entity
• Get Field Info: Retrieve field definitions for the selected entity

Advanced Features

• Resource Mapping: Dynamically map fields based on entity definitions
• Advanced Filtering: Build complex queries with multiple conditions
• File-based Caching: Improved performance with persistent caching that can be shared between workflows and runs
• Timezone Handling: Automatic conversion between local time and UTC

AI Tool Integration

This node can be used as a tool by AI agents in n8n workflows. This allows AI agents to interact with Autotask PSA, performing operations like retrieving company information, creating tickets, or updating contacts.

Requirements

Currently, n8n only allows core nodes to be used as tools by default. To use this community node as a tool, you need to:

1. Set the environment variable N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE to true when running n8n.
2. Add the Autotask node as a tool in your AI agent workflow.

Example AI Tool Usage

An AI agent might use the Autotask node to:

• Retrieve information about a company or contact
• Create a new ticket based on user input
• Update the status of an existing ticket
• Add notes to a ticket or company record
• Search for tickets matching specific criteria

Usage

Basic Example: Creating a Ticket

1. Add an Autotask node to your workflow
2. Select Ticket as the resource
3. Select Create as the operation
4. Configure the required fields (Title, Status, etc.)
5. Connect to a trigger or previous node
6. Execute the workflow

Intermediate Example: Querying Projects with Filters

1. Add an Autotask node to your workflow
2. Select Project as the resource
3. Select Get Many as the operation
4. Add filter conditions (e.g., Status equals "Active")
5. Choose whether to retrieve all results or limit the number:
   • Toggle "Get All" to true to retrieve all matching records
   • Toggle "Get All" to false and set "Max Records" (1-500) to limit the results
6. Connect to a trigger or previous node
7. Execute the workflow

Advanced Example: Complex Filtering with Get Many Advanced

1. Add an Autotask node to your workflow
2. Select Ticket as the resource
3. Select Get Many Advanced as the operation
4. Build a complex filter, for example:

   {
     "op": "and",
     "items": [
       {
         "field": "Status",
         "op": "notEqual",
         "value": 5
       },
       {
         "op": "or",
         "items": [
           {
             "field": "Priority",
             "op": "Equal",
             "value": 6
           },
           {
             "field": "DueDateTime",
             "op": "lessThan",
             "value": "{{ $now.plus(3, 'days').toLocal()}}"
           }
         ]
       }
     ]
   }

5. Choose whether to retrieve all results or limit the number:
   • Toggle "Get All" to true to retrieve all matching records
   • Toggle "Get All" to false and set "Max Records" (1-500) to limit the results
6. Execute the workflow to retrieve tickets that are not complete AND either have priority 6 OR are due within the next 3 days

Advanced Example: Working with Parent-Child Relationships

Many Autotask entities have parent-child relationships (e.g., Companies and Contacts). To work with these:

1. First, retrieve or create the parent entity
2. Use the parent entity's ID in the child entity operations
3. For example, to create a Contact for a Company:
   • First node: Get or create the Company
   • Second node: Create a Contact with the Company ID

Configuration

Caching Options

The node includes an enhanced file-based caching system to improve performance by reducing API calls:

• Enable Field Caching: Toggle caching on/off
• Cache TTL: How long to cache field values (in seconds)
• Cache Entity Info: Whether to cache entity information and field definitions
• Entity Info TTL: How long to cache entity information
• Cache Reference Fields: Whether to cache reference field values
• Reference Fields TTL: How long to cache reference field values
• Cache Picklists: Whether to cache picklist values
• Picklists TTL: How long to cache picklist values
• File-based Cache: Cache is stored in files that can be shared between workflows and runs
• Cache Directory: Optional path to a directory where cache files will be stored

Timezone Handling

All dates and times in the Autotask API are in UTC. The node automatically converts between your selected timezone and UTC:

• When creating or updating records, local times are converted to UTC
• When retrieving records, UTC times are converted to your local timezone
• The timezone is configured in the credentials

Limitations

API Limits

• Maximum 500 records per page in query results
• Maximum 50 pages per query operation
• Maximum 500 OR conditions in filters
• Maximum 1 User Defined Field per query

Entity-Specific Limitations

• Some entities may not support all operations (e.g., Project Phases cannot be deleted)
• Parent-child relationships require specific handling
• Some fields may be read-only or have specific validation rules

Performance Considerations

• Large queries may be slow and should be optimised with filters
• Complex workflows with many API calls may hit rate limits

Troubleshooting

Common Issues

• Authentication Errors: Verify your API credentials and ensure the API user has appropriate permissions
• Field Validation Errors: Check field requirements in the Autotask API documentation
• Rate Limiting: If you encounter rate limiting, reduce the frequency of API calls or implement retry logic

Reporting Bugs

If you encounter any bugs or issues with this integration:

1. Check the GitHub Issues to see if the problem has already been reported
2. If not, please submit a new issue with:
   • A clear description of the problem
   • Steps to reproduce the issue
   • Expected vs actual behaviour
   • Your environment details (n8n version, Node.js version)
   • Any relevant error messages or screenshots

Bug reports should be submitted via GitHub at: https://github.com/msoukhomlinov/n8n-nodes-autotask/issues

Resources

• Autotask API Documentation
• n8n Documentation
• GitHub Repository

License

MIT