n8n OpenProject Node V1.0.2

A comprehensive n8n node for integrating with OpenProject API. This node allows you to manage projects, work packages, and time entries directly from your n8n workflows.

Features

• Project Management: Create, read, update, and list projects
• Work Package Operations: Full CRUD operations for work packages
• Time Tracking: Create and manage time entries
• Dynamic Loading: Automatic loading of projects, users, and activities
• Error Handling: Robust error handling and validation
• OpenProject API v3: Full support for the latest OpenProject API

Installation

For n8n Cloud users

This node is available in the n8n Cloud marketplace. Simply search for "OpenProject" in the node library.

For self-hosted n8n

npm install n8n-nodes-openproject

Setup

1. Create an API token in OpenProject:

   • Go to your user profile in OpenProject
   • Navigate to "Access Token"
   • Create a new token with appropriate permissions

2. Configure credentials in n8n:

   • Base URL: Your OpenProject instance URL (e.g., https://mi.openproject.local)
   • API Token: The token you created in step 1

Resources

Project

• Get All: Retrieve all projects
• Get: Get a specific project by ID
• Create: Create a new project
• Update: Update an existing project

Work Package

• Get All: Retrieve all work packages
• Get: Get a specific work package by ID
• Create: Create a new work package
• Update: Update an existing work package

Time Entry

• Get All: Retrieve all time entries
• Get All by Work Package: Get all time entries for a specific work package
• Create: Create a new time entry

Usage Examples

Create a Work Package

{
  "resource": "workPackage",
  "operation": "create",
  "subject": "New Task",
  "projectId": "1",
  "type": "Task",
  "description": "Task description",
  "status": "New",
  "priority": "Normal"
}

Create a Time Entry

{
  "resource": "timeEntry",
  "operation": "create",
  "workPackageId": "1",
  "hours": "PT2H",
  "date": "2024-01-15",
  "comment": "Work done on this task"
}

Development Guide

Prerequisites

• Node.js: >= 16.0.0
• npm: >= 8.0.0
• Git: For version control
• OpenProject Instance: For testing (can be local or cloud)

Initial Setup

1. Clone the repository:

   git clone https://gitlab.com/somitcoop/projects/coopflow/n8n-nodes-openproject.git
   cd n8n-nodes-openproject

2. Install dependencies:

   npm install

3. Verify installation:

   npm run lint

Development Workflow

Building the Node

# Development build with watch mode
npm run dev

# Production build
npm run build

# Clean build (remove dist folder first)
rm -rf dist && npm run build

Code Quality

# Run linter
npm run lint

# Fix linting issues automatically
npm run lintfix

# Format code with Prettier
npm run format

Testing Locally

1. Build the node:

   npm run build

2. Install in local n8n:

   # Create custom nodes directory
   mkdir -p ~/.n8n/custom/nodes/n8n-nodes-openproject
      
   # Copy built files
   cp -r dist/* ~/.n8n/custom/nodes/n8n-nodes-openproject/
   cp package.json ~/.n8n/custom/nodes/n8n-nodes-openproject/

3. Restart n8n:

   # If using n8n locally
   n8n start
      
   # If using Docker
   docker restart n8n

4. Test in n8n:

   • Open n8n in your browser
   • Add the OpenProject node to a workflow
   • Configure credentials
   • Test different operations

Testing with Example Workflow

1. Import the example workflow:

   • Open n8n
   • Go to Workflows
   • Click "Import from file"
   • Select src/nodes/OpenProject/example.json

2. Configure credentials:

   • Add your OpenProject API credentials
   • Update the workflow parameters as needed

3. Run the workflow:

   • Activate the workflow
   • Monitor the execution
   • Check the results

Project Structure

src/
├── nodes/OpenProject/
│   ├── OpenProject.node.ts          # Main node logic
│   ├── GenericFunctions.ts          # API helper functions
│   ├── ProjectDescription.ts        # Project resource configuration
│   ├── WorkPackageDescription.ts    # Work Package resource configuration
│   ├── TimeEntryDescription.ts      # Time Entry resource configuration
│   ├── openproject.svg              # Node icon
│   ├── example.json                 # Example workflow
│   └── README.md                    # Node-specific documentation
├── credentials/
│   └── OpenProjectApi.credentials.ts # Credentials configuration
└── index.ts                         # Main entry point

dist/                                # Built files (generated)
├── nodes/OpenProject/
│   └── OpenProject.node.js
└── credentials/
    └── OpenProjectApi.credentials.js

Configuration Files

TypeScript Configuration (tsconfig.json)

• Target: ES2022
• Module: CommonJS
• Strict mode enabled
• Source maps for debugging

Webpack Configuration (webpack.config.js)

• Production mode for builds
• TypeScript loader
• Node.js target
• External dependencies for n8n

Package Configuration (package.json)

• n8n node metadata
• Build scripts
• Dependencies and devDependencies
• Publishing configuration

Publishing Guide

Prerequisites for Publishing

1. npm Account: Create an account at https://www.npmjs.com/signup
2. Unique Package Name: Ensure n8n-nodes-openproject is available
3. Git Repository: All changes committed and pushed

Publishing Process

1. Prepare for Publishing

# Ensure all changes are committed
git add .
git commit -m "Prepare for publishing v1.0.0"
git push origin main

# Verify build works
npm run build

# Check package contents
npm pack --dry-run

2. Login to npm

# Check if already logged in
npm whoami

# If not logged in, login
npm login
# Enter your username, password, and email

3. Publish the Package

# Publish to npm
npm publish

# For scoped packages (if needed)
npm publish --access public

4. Verify Publication

# Check if package is published
npm view n8n-nodes-openproject

# Install and test the published package
npm install n8n-nodes-openproject

Version Management

Updating Versions

# Patch version (bug fixes)
npm version patch

# Minor version (new features)
npm version minor

# Major version (breaking changes)
npm version major

Publishing Updates

# After version bump
git add .
git commit -m "Release v1.0.1"
git push origin main
git push --tags

# Publish new version
npm publish

Troubleshooting Publishing

Common Issues

1. Package name already taken:

   # Check availability
   npm view n8n-nodes-openproject
      
   # If taken, update package.json with new name
   # Example: n8n-nodes-openproject-custom

2. Authentication issues:

   # Re-login to npm
   npm logout
   npm login

3. Build errors:

   # Clean and rebuild
   rm -rf dist node_modules package-lock.json
   npm install
   npm run build

Contributing

Development Setup

1. Fork the repository

2. Create a feature branch:

   git checkout -b feature/amazing-feature

3. Make your changes:

   # Edit files
   npm run dev  # Watch mode for development
   npm run lint # Check code quality

4. Test your changes:

   npm run build
   # Test in local n8n instance

5. Commit and push:

   git add .
   git commit -m "Add amazing feature"
   git push origin feature/amazing-feature

6. Create a Pull Request

Code Standards

• TypeScript: Use strict mode
• ESLint: Follow linting rules
• Prettier: Use consistent formatting
• Testing: Test all new features
• Documentation: Update README for new features

Pull Request Guidelines

1. Clear description of changes
2. Test coverage for new features
3. Documentation updates if needed
4. No breaking changes without major version bump
5. Follow existing code style

API Reference

For more information about the OpenProject API, visit: https://www.openproject.org/docs/api/

OpenProject API Endpoints Used

• Projects: /api/v3/projects
• Work Packages: /api/v3/work_packages
• Time Entries: /api/v3/time_entries
• Users: /api/v3/users
• Types: /api/v3/types
• Statuses: /api/v3/statuses
• Priorities: /api/v3/priorities

Support

• Issues: GitLab Issues
• Email: [email protected]
• Documentation: This README and inline code comments

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

1.0.0

• Initial release
• Project management operations (CRUD)
• Work package operations (CRUD)
• Time entry management
• Dynamic loading of options
• Comprehensive error handling
• OpenProject API v3 support

Roadmap

Future Versions

• [ ] User management operations
• [ ] File attachment support
• [ ] Webhook support
• [ ] Bulk operations
• [ ] Advanced filtering options
• [ ] Custom field support