n8n-nodes-toggl/README.md

n8n community node for Toggl Track time tracking integration with comprehensive operations including client management and webhook support

# n8n-nodes-toggl

![Toggl Logo](./nodes/Toggl/toggl.png)

This is an n8n community node that provides integration with Toggl Track time tracking service. It lets you use Toggl Track in your n8n workflows.

[Toggl Track](https://toggl.com/track/) is a popular time tracking application used by individuals and teams to track time spent on various projects and tasks.

## Installation

Follow the [installation guide](https://docs.n8n.io/integrations/community-nodes/installation/) in the n8n community nodes documentation.

### Community Nodes (Recommended)

1. Go to **Settings > Community Nodes**.
2. Select **Install**.
3. Enter `n8n-nodes-toggl` in **Enter npm package name**.
4. Agree to the [risks](https://docs.n8n.io/integrations/community-nodes/risks/) of using community nodes.
5. Select **Install**.

After installation, you'll find the **Toggl** and **Toggl Webhook Trigger** nodes in the nodes panel.

### Manual Installation

To get started with development:

```bash
# Clone the repository
git clone https://github.com/example/n8n-nodes-toggl.git
cd n8n-nodes-toggl

# Install dependencies
pnpm install

# Build the nodes
pnpm build

# Link to n8n
cd ~/.n8n/nodes
ln -s /path/to/n8n-nodes-toggl/dist/nodes/Toggl n8n-nodes-toggl
```

## Credentials

You need to set up Toggl API credentials to use this node:

### Toggl API Token

1. Go to your [Toggl Profile settings](https://track.toggl.com/profile).
2. Scroll down to the **API Token** section.
3. Copy your API token.
4. In n8n, create new **Toggl API** credentials.
5. Paste your API token in the **API Token** field.

## Compatibility

This node requires n8n version 0.187.0 or later.

## Usage

### Toggl Node

The Toggl node supports the following operations:

#### Time Entry Operations
- **Start Time Entry**: Start a new time entry with optional project and tags
- **Stop Time Entry**: Stop a running time entry (by ID or current)
- **Get Current Time Entry**: Retrieve the currently running time entry
- **List Time Entries**: Get time entries with date filtering and pagination

#### Project Operations
- **Create Project**: Create a new project in a workspace
- **List Projects**: Get projects from a workspace with optional archived filter

#### Client Operations
- **Create Client**: Create a new client in a workspace with optional external reference and notes
- **List Clients**: Get clients from a workspace with status filtering (active, archived, both) and name filtering

#### Raw Request
- **Raw Request**: Make custom API calls to any Toggl endpoint

### Toggl Webhook Trigger

The webhook trigger node allows you to receive real-time notifications when events occur in Toggl:

- **Project Events**: created, updated, deleted
- **Time Entry Events**: created, updated, deleted  
- **Task Events**: created, updated, deleted

The webhook trigger automatically:
- Creates webhook subscriptions with Toggl
- Validates webhook signatures for security
- Manages subscription lifecycle (create/delete)

## Sample Workflow

Here's a sample workflow that starts a time entry when a new task is created in another system:

```json
{
  "meta": {
    "instanceId": "example"
  },
  "nodes": [
    {
      "parameters": {},
      "name": "Start",
      "type": "n8n-nodes-base.start",
      "typeVersion": 1,
      "position": [240, 300],
      "id": "start-node"
    },
    {
      "parameters": {
        "resource": "timeEntry",
        "operation": "startTimeEntry",
        "description": "Working on {{$json.task_name}}",
        "projectId": "={{$json.project_id}}",
        "tags": "automated,n8n"
      },
      "name": "Start Toggl Timer",
      "type": "n8n-nodes-toggl.toggl",
      "typeVersion": 1,
      "position": [460, 300],
      "id": "toggl-node",
      "credentials": {
        "togglApi": {
          "id": "1",
          "name": "Toggl API"
        }
      }
    }
  ],
  "connections": {
    "Start": {
      "main": [
        [
          {
            "node": "Start Toggl Timer",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  }
}
```

### Webhook Workflow Example

Here's a workflow that triggers when a time entry is created in Toggl:

```json
{
  "meta": {
    "instanceId": "example"
  },
  "nodes": [
    {
      "parameters": {
        "workspaceId": 123456,
        "events": ["time_entry:created", "time_entry:updated"],
        "description": "n8n automation webhook"
      },
      "name": "Toggl Webhook",
      "type": "n8n-nodes-toggl.togglWebhookTrigger",
      "typeVersion": 1,
      "position": [240, 300],
      "id": "webhook-trigger",
      "credentials": {
        "togglApi": {
          "id": "1",
          "name": "Toggl API"
        }
      },
      "webhookId": "webhook-id"
    },
    {
      "parameters": {
        "options": {}
      },
      "name": "Process Time Entry",
      "type": "n8n-nodes-base.function",
      "typeVersion": 1,
      "position": [460, 300],
      "id": "function-node"
    }
  ],
  "connections": {
    "Toggl Webhook": {
      "main": [
        [
          {
            "node": "Process Time Entry",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  }
}
```

## Common Use Cases

1. **Project Management Integration**: Automatically start/stop timers when tasks change status
2. **Reporting**: Extract time tracking data for custom reports and dashboards
3. **Team Coordination**: Send notifications when team members start/stop work
4. **Billing Automation**: Generate invoices based on tracked time
5. **Productivity Monitoring**: Track and analyze work patterns

## API Reference

This node uses the [Toggl Track API v9](https://developers.track.toggl.com/docs/). All operations support the same parameters and return the same data structures as the official API.

### Rate Limiting

The node automatically handles Toggl's rate limiting (429 responses) with exponential backoff retry logic.

### Error Handling

API errors are properly wrapped and include helpful error messages. Enable "Continue on Fail" in node settings to handle errors gracefully in your workflows.

## Development

### Building

```bash
pnpm build
```

### Testing

```bash
pnpm test
```

### Linting

```bash
pnpm lint
pnpm lintfix
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass and linting is clean
6. Submit a pull request

## License

[MIT](LICENSE.md)

## Resources

- [n8n community nodes documentation](https://docs.n8n.io/integrations/community-nodes/)
- [Toggl Track API documentation](https://developers.track.toggl.com/docs/)
- [Toggl Track website](https://toggl.com/track/)

## Support

For questions about this node, please [open an issue](https://github.com/example/n8n-nodes-toggl/issues) on GitHub.

For general n8n support, visit the [n8n community forum](https://community.n8n.io/).