Skip to Content

OpenProject

Last modified by Vincent Massol on 2026/06/03 14:15

Implementation Details

Must Haves

 REQM01: Be able to issue queries to find issues (e.g. JQL for JIRA), including global search in all projects. It's used in lots of places, including on hundreds of pages on xwiki.org

Warning

It's possible to filter (but in much less powerful way than JIRA's JQL, which will be a problem to migrate the thousands of JQL queries existing on xwiki.org) in 2 ways:

  • Using the advanced search
  • Using the Filter button in the work package view.

The later allows to copy the URL and share it. The former doesn't.

There's also a REST API to Query work packages, including setting filters, and there's an OP Contrib Macro that uses that REST API to display work packages. There's also an XWiki SAS company OP Pro extension that adds features and which documents how to perform filters.

 REQM02: Be able to label issues. We're using the following labels

Implemented as a "Labels" custom field using a List so that we control the labels that can be used.

 REQM03: Be able to have several resolutions for issues (Won't fix, Fixed, Duplicate, Solved By, etc.)

There's no concept of "resolution". Only a concept of "statuses".

We have 2 options:

  1. Fold the concept of resolution inside the concept of statuses.
  2. Introduce a custom field for Resolution. See below for custom fields.

Option 1 has the advantage that we can mark a status entry as being 100% complete and marking the work package as closed. 

If we go with option 2 then there's no relationship between resolution and statuses (we cannot force the user to set a Resolution). Note that there's the concept of "automatic action" but it's limited and cannot be used to solve the problem. See https://op.xwiki.org/admin/custom_actions

Thus option 1 has been implemented.

 REQM04: Be able to have categories (components in JIRA parlance)

Categories are set per project. See for example:

 REQM05: Be able to automatically link GitHub commits with JIRA issues (i.e., links from JIRA to the commits)

Error

Seems it's only possible to link to GH PRs. See https://community.openproject.org/projects/OP/work_packages/OP-19441/activity

Only the following GH webhook events are supported (all others return a 404 from OP): https://github.com/opf/openproject/blob/v16.6.1/modules/github_integration/lib/open_project/github_integration/hook_handler.rb#L31-L37

This means that "push" events (which happen when a commit is pushed) are not supported and we cannot track git commits in OP work packages emoticon_unhappy

For now, you should still commit using the following format:

OP#<issue number>: <issue title>
<* optional additional information>

For example:

OP#49: Add a Documentation class for UIXP + add a UIX
* Also fix a bug in RenderingMacrosUIX and DocumentationSheet to allow supporting more than 1 UIX

 REQM06: Be able to have several issue types

See https://op.xwiki.org/types

 REQM07: Be able to have graphs to follow, for example, the number of bugs created vs resolved

Warning

Some limited graphs per project:

 REQM08: Be able to have REST endpoints to create XWiki macros (e.g., the JIRA macro) or scripting in xwiki pages

See https://www.openproject.org/docs/api/

 REQM09: Be able to have several projects (one for each repo)

See https://op.xwiki.org/projects

 REQM10: Be able to have several groups (categories in JIRA parlance)

Projects can be nested so the solution is to create a container project.

For example:

 REQM11: Be able to mass refactor issues (select issues with a query and then apply changes to all of them: add a fix version, etc.)

There's the concept of Bulk Edit.

 REQM12: Be able to set permissions/groups/roles for authorization

See https://op.xwiki.org/users

 REQM13: Be publicly accessible
 REQM14: Be able to self-register and create issues

See https://op.xwiki.org/admin/settings/authentication?tab=registration

When a user self-registers, he/she is part of the "Non-Member" role by default. Thus we need to define the permissions of the "Non-Member" role to allow creation of work packages, etc.

 REQM15: Be able to have shared schemes to share configs between projects (permission scheme, workflow scheme, etc.)

Doesn't exist but there's the concept of Project Template. However, that's very painful as it's a copy and not a reference (i.e. if the template is modified then the existing projects created from that template are not updated).

This will lead to more maintenance and duplication. OTOH there are lots of features not available at the project level and which can thus only be configured at the global level (like workflows). For permissions for ex, we'll need to set it up for each project, using roles, to reduce maintenance.

 REQM16: Be able to define custom fields (we use that for documentation and flickering tests for example)

Generally possible, see https://op.xwiki.org/admin/settings/project_custom_fields

Warning

However, to implement our custom Reference Documentation field, it's not possible to use the Link type since we can have more than 1 URLs and OP doesn't support having a list of URLs...
The only solution right now is to use a Long text (textarea) but it has some drawbacks:

  • It's not possible to display it as a column in the Work Package lists (since it's a textarea)
  • We cannot put a good regex for it (the best we can do is ^https://|^N\/A$) but that means that users can start the content with a URL and then type whatever they want, without it being stricly URLs

 REQM17: Be able to receive notifications (individual or to a notification list)

See https://www.openproject.org/docs/user-guide/notifications/

 REQM18: Be able to import existing issues from the current issue tracker (e.g. JIRA) and not loose metadata ideally

Warning

Very rudimentary ATM for JIRA import but it seems the OP devs are working on a better JIRA import.

We have 4 solutions:

  1. Wait for the official JIRA importer to be ready
  2. Use the JIRA and OP REST APIs and write code
  3. Try out the OP JIRA importer (but I doubt it'll do all that we need)
  4. Don't import from JIRA and only use OP for new projects. Keep the JIRA instance in read-only mode. At least until the official JIRA importer is ready and good enough

Solution 4 seems to be the only reasonable one since we have thousands of JIRA queries on xwiki.org (using JQL for a lot of them, that we cannot easily convert or it would take a lot of time to do so).

 REQM19: Be able to move issues (and not have to close and copy issues)

It's possible to move work packages between project and set some properties at the same time. See https://www.openproject.org/docs/user-guide/work-packages/duplicate-move-delete/

 REQM20: Be able to link between issues (“depends on”, “is related to”, etc.)

Each work packages has a "Relations" tab with plenty of available type of relations.

TODO: Check if relations can be customized/configured (to remove some for example)

 REQM21: Be able to see the detailed history of the issue

Available in the "Activity" tab of each work package.

 REQM22: Be able to add attachments and display pictures/video integrations

Attachments can be added to work packages, and images can also be added in comments of work packages (in this case the images are not visible uner the File tab). Images can be added by upload, copy/paste or drag and drop.

Warning

 REQM23: Be able to have priorities, including a Blocker priority.

See https://op.xwiki.org/admin/settings/work_package_priorities

 REQM24: Be able to have statuses (open, in progress, closed)

See https://op.xwiki.org/statuses

 REQM25: Be able to self-register confidential issues (e.g. for security issues)

Error

It's not possible.

It's not even possible to set permissions on a work package. A workaround would be to create a confidential sub project with proper permissions but it's a major pain to maintain as subprojects don't inherit everything from their parent projects, causing lots of manual maintenance (e.g. categories).

 REQM26: Be able to have different fields for different projects (e.g. some projects don't have the notion of Version)

Error

Doesn't seem possible. The field organization seem to apply to all projects (you can only configure them differently per work package type).

Could also be useful to have some internal project where we define the yearly roadmap and use the workload fields to estimate the capacity. I guess this could be achieved with a new type but then this type could also be chosen for other projects, which shouldn't be possible.

Nice to Have

 REQN01: Be able to have dashboards for releases (e.g. JIRA Dashboard)

Not configurable. See for ex https://community.openproject.org/versions/1413

 REQN02: Be able to see similar issues when creating new issues to avoid duplicating existing issues

Not found.

 REQN03: Be able to execute scripts inside the issue tracker to query issues and perform changes

Not found. There's an experimental CLI but it cannot be used to execute scripts.

 REQN04: Be able to link issues with issues from an external bug tracker (Apache JIRA instance, etc.)

Not found. But could be implemented using a custom field (but it won't show the status dynamically).

 REQN05: Be able to sponsor issues (e.g. we used to use FreedomSponsors in the past)

Not found.

Additional

 Ability to list project attributes on the project home page.

We have defined the following attributes:

  • Extension URL: Link to where the top-level extension for this project can be found on extensions.xwiki.org
  • Lead: The lead of the project (for contrib projects)

For ex, see https://op.xwiki.org/projects/latex/

 Be able to set several fix Versions

Error

The built-in "Version" field only accepts a single value. There's a WP open to ask to make it multi-valued.

Custom Version fields can be multi-valued but by doing so we would loose features such as the Roadmap UI which works only with the built-in "Version" field. There might be other features using the built-in "Version" field.

A workaround is to introduce a "Backport Versions" field but again it means that roadmaps will not be correct and the work packages with versions specified in the "Backport Versions" field won't appear in Release notes for these versions.

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected