Content
View differences
Updated by Dominic Bräunlein 3 days ago
**As** an administrator of an OpenProject instance
**I want to** set up an integration with XWiki
**so that** users of my instance (project members, project admins, stakeholders) may access, link to and create wiki pages via OpenProject
####
**Acceptance criteria**
Before OpenProject project members are able to access, link to and create wiki pages in XWiki, an administrator has to set up the integration. This is a one-time operation per wiki instance.
* There is a new entry in the administration settings, at _Administration → Wiki platforms_
* This will display all existing integrations with wiki platforms. By default it is empty.
* Administrators can click on the **\+ Wiki platform** button and select "XWiki" to be taken to the "New XWiki instance" page where they can begin configuring the integration.
* Setting up an XWiki-OpenProject integration involves three main steps on the OpenProject side, through which the users are guided step-by-step:
* In _General information_, the admin user gives the XWiki instance to which they're connecting a name and defines the host URL.
* In _OAuth applications_, there is an exchange of OAuth client IDs and secrets between the two applications.
* OpenProject will generate its own values that the user will have to paste into the OpenProject integration setup flow in XWiki.
* XWiki will, in turn, also generate a client ID and secret that the user will be asked to enter on this page.
* (Not part of the initial scope of implementation offer) In _Project spaces_, the admin user can choose to let OpenProject automatically create individual wiki spaces for each project (in which the XWiki module is enabled).
* The user will be asked to enter an application password generated on XWiki to grant OpenProject the ability to manage these spaces.
* If the user does not enable automatically-managed spaces, they will have to manually pick spaces for each wiki page created via OpenProject.
* In _My account / Access tokens_ the current user can revoke/delete each access token that was granted to each XWiki instance.
#### Prerequisites
* XWiki instance is reachable
* XWiki instance provides an info endpoint so that OpenProject can verify that a minimal expected version is available.
* version number of XWiki
* (in case it is managed separately) version number of the OpenProject integration code
* Connection to XWiki instance is TLS encrypted as required by the OAuth2 standard
* The CA certificate for the XWiki TLS certificate is either a generally known CA or is provided during OpenProject boot time
#### Future development
* **Health checks:** For each wiki platform, there is a periodic health check to ensure the connection and the integration function as intended.
* If there are any complications like a connection error, or an authentication error, these are displayed immediately, along with the last time a check was performed.
* The admin can also choose to be notified by email for any updates to the health of an XWiki integration so that they can be informed as quickly as possible.
#### **Visuals**
**Empty "Wiki platforms" page (no integration added yet):**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/107167/content">
**Step 1: General information:**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/107168/content">
**Step 2A: OAuth client IDs and secrets (OpenProject-generated):**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/107169/content">
**Step 2B: OAuth client IDs and secrets (XWiki-generated):**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/107170/content">
**Step 3: Automatically managed project spaces (Not part of the initial scope of implementation offer):**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/107171/content">
**XWiki instance added:**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/107172/content">
**Health checks - all okay:**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/107173/content">
**Health check - problems detected:**
**<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/918228/content">**
#### **Figma mockups**
* **Integration setup:** [https://www.figma.com/design/m0Aj4o5upRvD2kdSB7mMQT/XWiki-Integration?node-id=304-33134&amp;t=8u8yBfPkViXQeEFt-4](https://www.figma.com/design/m0Aj4o5upRvD2kdSB7mMQT/XWiki-Integration?node-id=304-33134&t=8u8yBfPkViXQeEFt-4)
* **Health checks:** [https://www.figma.com/design/m0Aj4o5upRvD2kdSB7mMQT/XWiki-Integration?node-id=304-44961&amp;t=8u8yBfPkViXQeEFt-4](https://www.figma.com/design/m0Aj4o5upRvD2kdSB7mMQT/XWiki-Integration?node-id=304-44961&t=8u8yBfPkViXQeEFt-4)
# Information from the TOSIT Co-financing order 2025
## Section title
Centralized management of users and access rights
## Description
Ensures consistent, secure access control between OpenProject and XWiki: any viewing or action from one tool to the other strictly respects the user’s permissions in the target tool.
## Behavior
In XWiki, displaying content pulled from OpenProject (e.g., work packages, charts) checks the user’s OpenProject permissions. If access is missing, the macro is not displayed and a permissions error message is shown. In OpenProject, links to XWiki pages reflect the user’s XWiki permissions: if access is denied, the link is grayed out and non-clickable. When creating an OpenProject work package from XWiki, creation is only allowed if the user has the necessary permissions in OpenProject.
## Example
The integration systematically validates permissions in the target tool for any cross-tool action or display, ensuring secure and consistent access. The need for centralized license management is not included in this interoperability package.
**I want to** set up an integration with XWiki
**so that** users of my instance (project members, project admins, stakeholders) may access, link to and create wiki pages via OpenProject
####
Before OpenProject project members are able to access, link to and create wiki pages in XWiki, an administrator has to set up the integration. This is a one-time operation per wiki instance.
* There is a new entry in the administration settings, at _Administration → Wiki platforms_
* This will display all existing integrations with wiki platforms. By default it is empty.
* Administrators can click on the **\+ Wiki platform** button and select &quot;XWiki&quot; to be taken to the &quot;New XWiki instance&quot; page where they can begin configuring the integration.
* Setting up an XWiki-OpenProject integration involves three main steps on the OpenProject side, through which the users are guided step-by-step:
* In _General information_, the admin user gives the XWiki instance to which they&#39;re connecting a name and defines the host URL.
* In&nbsp;_OAuth applications_, there is an exchange of OAuth client IDs and secrets between the two applications.
* OpenProject will generate its own values that the user will have to paste into the OpenProject integration setup flow in XWiki.
* XWiki will, in turn, also generate a client ID and secret that the user will be asked to enter on this page.
* (Not part of the initial scope of implementation offer) In _Project spaces_, the admin user can choose to let OpenProject automatically create individual wiki spaces for each project (in which the XWiki module is enabled).
* The user will be asked to enter an application password generated on XWiki to grant OpenProject the ability to manage these spaces.
* If the user does not enable automatically-managed spaces, they will have to manually pick spaces for each wiki page created via OpenProject.
* In _My account / Access tokens_ the current user can revoke/delete each access token that was granted to each XWiki instance.
* XWiki instance is reachable
* XWiki instance provides an info endpoint so that OpenProject can verify that a minimal expected version is available.
* version number of XWiki
* (in case it is managed separately) version number of the OpenProject integration code
* Connection to XWiki instance is TLS encrypted as required by the OAuth2 standard
* The CA certificate for the XWiki TLS certificate is either a generally known CA or is provided during OpenProject boot time
####
* **Health checks:** For each wiki platform, there is a periodic health check to ensure the connection and the integration function as intended.
* If there are any complications like a connection error, or an authentication error, these are displayed immediately, along with the last time a check was performed.
* The admin can also choose to be notified by email for any updates to the health of an XWiki integration so that they can be informed as quickly as possible.
#### **Visuals**
**Empty &quot;Wiki platforms&quot; page (no integration added yet):**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/107167/content">
**Step 1: General information:**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/107168/content">
**Step 2A: OAuth client IDs and secrets (OpenProject-generated):**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/107169/content">
**Step 2B: OAuth client IDs and secrets (XWiki-generated):**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/107170/content">
**Step 3: Automatically managed project spaces (Not part of the initial scope of implementation offer):**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/107171/content">
**XWiki instance added:**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/107172/content">
**Health checks - all okay:**
<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/107173/content">
**Health check - problems detected:**
**<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/918228/content">**
#### **Figma mockups**
* **Integration setup:** [https://www.figma.com/design/m0Aj4o5upRvD2kdSB7mMQT/XWiki-Integration?node-id=304-33134&amp;t=8u8yBfPkViXQeEFt-4](https://www.figma.com/design/m0Aj4o5upRvD2kdSB7mMQT/XWiki-Integration?node-id=304-33134&t=8u8yBfPkViXQeEFt-4)
* **Health checks:** [https://www.figma.com/design/m0Aj4o5upRvD2kdSB7mMQT/XWiki-Integration?node-id=304-44961&amp;t=8u8yBfPkViXQeEFt-4](https://www.figma.com/design/m0Aj4o5upRvD2kdSB7mMQT/XWiki-Integration?node-id=304-44961&t=8u8yBfPkViXQeEFt-4)
# Information from the TOSIT Co-financing order 2025
## Section title
Centralized management of users and access rights
## Description
Ensures consistent, secure access control between OpenProject and XWiki: any viewing or action from one tool to the other strictly respects the user’s permissions in the target tool.
## Behavior
In XWiki, displaying content pulled from OpenProject (e.g., work packages, charts) checks the user’s OpenProject permissions. If access is missing, the macro is not displayed and a permissions error message is shown. In OpenProject, links to XWiki pages reflect the user’s XWiki permissions: if access is denied, the link is grayed out and non-clickable. When creating an OpenProject work package from XWiki, creation is only allowed if the user has the necessary permissions in OpenProject.
## Example
The integration systematically validates permissions in the target tool for any cross-tool action or display, ensuring secure and consistent access. The need for centralized license management is not included in this interoperability package.