OpenProject icon

OpenProject

Interact with OpenProject via API
Join our community

Actions199

Overview

This node operation allows you to list work packages from an OpenProject instance via its API. It is useful for retrieving paginated, filtered, sorted, and grouped collections of work packages, which are units of work or tasks within projects managed in OpenProject.

Common scenarios include:

  • Fetching a list of work packages assigned to specific users or groups.
  • Retrieving work packages filtered by status, priority, or custom fields.
  • Displaying work packages sorted by due date or grouped by status.
  • Integrating OpenProject work package data into other workflows or reporting tools.

For example, you could use this node to get all open bugs (work packages of type "bug") assigned to a team member, sorted by priority, to feed into a dashboard or notification system.

Properties

Name Meaning
Offset Page number inside the requested collection. Used for pagination to specify which page of results to retrieve.
Page Size Number of elements to display per page. Controls how many work packages are returned in one request.
Filters JSON string specifying filter conditions to apply when listing work packages. Accepts the same format as the OpenProject queries endpoint. Supports filtering by many fields such as assigned user, status, priority, project, type, dates, custom fields, and more. If empty array [] is provided, no filters are applied; otherwise, a default filter is used. Example: [{"type_id": {"operator": "=", "values": ["1", "2"]}}] filters by type IDs 1 and 2.
Sort By JSON string specifying sort criteria, following the OpenProject queries endpoint format. Defines how the results should be ordered, e.g., by status ascending or due date descending. Default is [["status", "asc"]].
Group By The column name to group the results by, e.g., "status". This organizes the returned work packages into groups based on the specified field.
Show Sums Boolean indicating whether numeric properties that support summation should be summed up in the response. For example, estimated hours might be totaled per group.
Select Comma separated list of properties to include in the response. Controls which fields are returned for each work package. Default includes total count, subject, ID, and self link.
Timestamps Comma separated ISO-8601 timestamps or relative date keywords for baseline comparison of work packages. Allows comparing work package states at different points in time. Examples include absolute dates like "2022-01-01T00:00:00Z" or relative times like "oneDayAgo@01:00+01:00". Older values require a valid Enterprise Token. Default is "2022-01-01T00:00:00Z,PT0S".

Output

The node outputs JSON data representing the list of work packages retrieved from OpenProject. The structure typically includes:

  • total: Total number of work packages matching the query.
  • elements: An array of work package objects, each containing selected fields such as id, subject, and other requested properties.
  • Additional metadata such as grouping information if groupBy was used.
  • Summed properties if showSums is enabled.

If binary data were supported (e.g., attachments), it would be indicated here, but this operation focuses on JSON data only.

Dependencies

  • Requires an active connection to an OpenProject instance with appropriate API access.
  • Needs an API key credential configured in n8n for authentication.
  • The node uses OpenProject's REST API endpoints for queries and work package retrieval.
  • Proper network access to the OpenProject server URL is necessary.

Troubleshooting

  • Invalid Filter or Sort JSON: If the filters or sortBy properties contain malformed JSON, the API will reject the request. Ensure these inputs are valid JSON strings.
  • Authentication Errors: Missing or incorrect API credentials will cause authorization failures. Verify the API key and base URL configuration.
  • Pagination Issues: Using an offset or page size that exceeds available data may return empty results. Adjust pagination parameters accordingly.
  • Enterprise Token Required: Using timestamps older than one day for baseline comparisons requires a valid Enterprise Token. Without it, the API may reject the request.
  • API Rate Limits: Frequent requests may hit rate limits imposed by OpenProject. Implement retries or backoff strategies if needed.

Links and References

Discussion