n8n-nodes-onoffice

This is an n8n community node for the OnOffice API. It allows you to use OnOffice in your n8n workflows.

Latest Update (v0.6.0)

This version adds task management functionality:

New OnOfficeTask Node: Create tasks in OnOffice CRM
Task Creation Support: Create tasks with subject, status, and relation to addresses or estates
API Stability Improvements: Fixed HMAC authentication for better reliability
Enhanced Error Handling: Better error reporting and debug information

Previous Update (v0.5.6)

This version includes critical fixes for the relation handling functionality:

Fixed Multiple Item Results: Relations nodes now properly process all related items from the API
Improved Response Handling: Better handling of different API response formats
Enhanced Error Resilience: Added fallback support for alternative data structures
Better Relation Type Support: Full support for all relation types across both relation nodes
Stable API Endpoint: Now using the stable API endpoint for more consistent results

Previous Update (v0.4.0)

This version features a completely redesigned UI approach with:

Form-based field selection: Visual selection of fields instead of manual JSON editing
Dynamic UI controls: Proper input types for each field (dropdowns, numbers, text areas)
Improved data flow: Load data from previous steps directly into update operations
Visual filtering: Create complex filters with an intuitive interface

These improvements make the node much more user-friendly while maintaining all functionality.

OnOffice is a CRM system specifically designed for real estate businesses. This node allows you to interact with the OnOffice API to manage estates, addresses, and their relationships.

⚠️ Important API Notes

This integration has been tested and works with the OnOffice API, but there are some important considerations:

Resource Availability: Not all OnOffice accounts have access to all resources. For example:
- The estate resource is usually available for all accounts
- The address resource might require specific field names that vary by account
- The idsfromrelation resource might show as "missing configuration" if not enabled for your account
Field Names: OnOffice uses specific field names for different resources. We've included documentation of common field names in the docs directory:
- docs/onoffice-estate-fields.md - Common fields for properties/estates
- docs/onoffice-address-fields.md - Common fields for addresses

Installation

Automated Installation (Recommended)

Open your n8n instance
Go to Settings > Community Nodes
Select "Install" and enter n8n-nodes-onoffice-api
Restart n8n

Manual Installation

Clone the repository:

git clone https://github.com/yourusername/onoffice-n8n-node.git

Navigate to the directory:
```
cd onoffice-n8n-node
```
Install dependencies:
```
npm install
```
Build the node:
```
npm run build
```
Link to your n8n installation:
```
npm link
```
In your n8n installation directory:
```
npm link n8n-nodes-onoffice-api
```

Docker Installation

Clone the repository
Navigate to the directory
Run ./start-docker.sh to build and start the Docker container
Access n8n at http://localhost:5678

Authentication

You need to obtain API credentials from your OnOffice account:

Contact OnOffice support to have the API enabled for your account
Once enabled, you'll receive an API Token and API Secret
Add these credentials to n8n in the "Credentials" section

Features

This integration provides a comprehensive node for OnOffice API access with an improved UI:

Resource Support

Estate Management: Create, retrieve, update, and filter property listings
Address Management: Create, retrieve, update, and filter contacts/addresses
Relation Management: Create and manage relationships between estates and addresses
Task Management: Create tasks and associate them with addresses and estates
Agent Log Management: Create agent activity logs with correct parameter structure

UI Improvements

Form-based Field Selection: Choose exactly which fields to include in each operation
Visual Filtering Interface: Build complex filter criteria using a user-friendly UI
Data Mapping: Easily load data from previous nodes when updating records
Field Type Support: Proper input types (dropdowns, numbers, textareas) for each field

Backward Compatibility

Advanced Mode: Option to use the original JSON-based approach for power users
Legacy Filters: Support for both new visual filters and legacy filter parameters

Estate Resource Fields

Here are some of the most commonly used fields for the estate resource:

Basic Information

Id - Unique record ID
objektnr_extern - External property number
objekttitel - Property title
objektbeschreibung - Property description
vermarktungsart - Marketing type (e.g. 'kauf', 'miete')
objektart - Property type (e.g. 'haus', 'wohnung')
objekttyp - Object type

Price and Financial Fields

kaufpreis - Purchase price
kaltmiete - Cold rent
warmmiete - Warm rent
nebenkosten - Additional costs
heizkosten - Heating costs

Property Features

wohnflaeche - Living space
anzahl_zimmer - Number of rooms
balkon - Balcony
terrasse - Terrace
baujahr - Year of construction

For a complete list of estate fields, see docs/onoffice-estate-fields.md.

Address Resource Fields

Common fields for the address resource include:

Vorname - First name
Name - Last name
Email - Email address
Strasse - Street
Ort - City

For a complete list of address fields, see docs/onoffice-address-fields.md.

Task Node

The OnOfficeTask node allows you to create tasks in OnOffice CRM:

Task Features

Create new tasks with subject information
Connect tasks to addresses and estates (experimental)
Set task priority, status, and due dates
Assign responsible users

Task Limitations

The OnOffice API has some limitations with task creation:

Field names must use specific German terms (e.g., "Betreff" for subject)
Some field combinations may cause API errors
Currently, only the subject field is guaranteed to work correctly

To get the most reliable results:

Start with the minimum required fields (subject)
Enable debug info to see the full request and response
Gradually add more fields to see which ones work with your OnOffice setup

Troubleshooting

Unknown Field Errors

If you encounter "Unknown field" errors, it's because OnOffice has different field names for different accounts. Try these steps:

Contact OnOffice support to get the correct field names for your account
Use the Debug node after the OnOffice node to see the full error message
Try the discover-fields.js script in the scripts directory to find valid field names

Missing Configuration Errors

If you see "missing configuration for resourceType X" errors, it means your OnOffice account does not have that feature enabled. Contact OnOffice support to enable it.

Authentication Errors

If you encounter authentication errors:

Verify your API Token and Secret are correct
Check that your OnOffice account has API access enabled
Use the test scripts in the scripts directory to test API connectivity directly

Development and Testing

This package includes several test scripts to help with development:

test-api.js: Basic OnOffice API testing
```
npm run test-api
```
test-n8n-api.js: Tests API using the same authentication method as the n8n node
```
npm run test-n8n-api
```
discover-fields.js: Helps discover valid field names for your OnOffice account
```
node scripts/discover-fields.js
```

Resources

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.