Open Project Integration (Pro)
Open Project Integration (Pro)
Connect to your OpenProject instance and display WorkPackages in XWiki as lists, cards or single items.
| Category | Application |
| Rating | |
| Support |
XWiki SAS
|
| License | GNU Lesser General Public License 2.1 |
| Minimal XWiki version supported | XWiki 14.10 |
| Sources | Issues |
OpenProject Integration (Pro) provides an intuitive and user friendly way to manage the Work Packages directly within XWiki, while keeping the knowledge and project management in only one place. The extension offers a simple way to setup the integration, allowing users to connect XWiki to an OpenProject instance quickly and securely. The authentication process requires minimal and easy to perform configuration, making the login experience straightforward.
Once connected, Work Packages can be displayed in XWiki using the OpenProject macro, which supports multiple configurable parameters to customize the output. Work packages can be viewed in different ways and the displayed information can be customized by selecting the needed Work Package properties.
Advanced filtering and sorting capabilities are available, combining XWiki’s native filters with existing OpenProject filters, which can be further extended directly in XWiki, enabling efficient navigation and organization of Work Packages.
Connect XWiki to OpenProject
In order to connect an XWiki instance to OpenProject, follow the next steps:
Create an OAuth Application in OpenProject
To configure the OAuth Application, go to the OAuth connections section in your OpenProject instance:
- Navigate to Administration by clicking the profile icon in the top navigation bar.
- From the left sidebar, select Authentication.
- Under the OAuth Applications section, click the OAuth application button.
This will allow you to define a new application. The following parameters are required for setting up the OAuth application:
| Name | Description | Default | Can be left unchanged |
|---|---|---|---|
| Active | Enable or disable this OAuth connection. When unchecked, the application will not be available for authentication purposes. The active value for an XWiki instance should be enabled | enabled | yes |
| Name | A descriptive name for this OAuth application. It helps identify the integration | - | no |
| Redirect URI | The URI to which the authorization server will redirect the user after authorization. This should point to your XWiki instance's callback endpoint. The authorization point value for an XWiki instance should be https://<your-xwiki-domain>/xwiki/oidc/authenticator/callback | - | no |
| Scopes | Check the scopes you want the application to grant access to. The scopes value for an XWiki instance should be api_v3 | api_v3 | yes |
| Confidential | Check if the application will be used where the client secret can be kept confidential. The confidential value for an XWiki instance should be enabled | true | yes |
Once the application is created, OpenProject will generate a Client ID and Client secret. These credentials must be securely stored and used in the further steps.
Create an OpenProject Connection in XWiki
To configure the connection with OpenProject from an XWiki instance, you need to create a new OpenProject connection within XWiki. The connection can be created from OpenProject section in the Administer Wiki area:
- Click on the Drawer icon (the icon in the top navbar, usually three horizontal lines or a grid)
- From the menu that opens, select Administer Wiki
- Go to Other
- Go to OpenProject
By using the Add New Connection button, you can open the modal where we can configure a connection to an OpenProject instance. Four parameters are required to define the connection.
| Name | Description | Required |
|---|---|---|
| Connection Name | The name of the connection to the OpenProject instance. This value must be unique among all connection names, you cannot have two instances with the same name | yes |
| Server URL | The URL of the OpenProject instance you want to connect to and for which the OAuth application has been created. The value must be the root path of the instance, for example:https://<your-open-project-instance> | yes |
| Client ID | Represents the value of the Client ID parameter, generated when the OAuth application was defined in the OpenProject instance | yes |
| Client Secret | Represents the value of the Client secret parameter, generated when the OAuth application was defined in the OpenProject instance | yes |
By pressing the Submit button, the new connection will be saved and created.
You can Edit or Delete any connection at any time using the Actions in the connections table. If the connection is not available (the current connection expired or is a new connection), you can use the third action (Reconnect) in order to reconnect.
Use the Open Project macro
The OpenProject macro allows you to display OpenProject Work Packages in XWiki and configure how they are presented, including the displayed properties and view mode.
Open Project Macro Parameters
The OpenProject macro can be configured using a set of parameters. These parameters allow you to customize the macro’s behavior and output depending on the needs. The currently available parameters are described below:
| Name | Description | Default | Required |
|---|---|---|---|
| Open Project Instance | The name of the Open Project instance that was configured in the administration section. | - | yes |
| Description | A description about the displayed Work Packages | - | no |
| Filters | The filters used to retrieve the work items. You can easily define these filters using the macro’s configuration modal. | - | no |
| Work package(s) identifier | A URL from the OpenProject instance pointing to work packages (either all Work Packages (https://<openproject-instance>/work_packages) or those from a specific project (https://<openproject-instance>/projects/<project-identifier>/work_packages), preserving any filters and sorting defined in the OpenProject UI when used in XWiki. | - | no |
| Limit | The maximum number of Work Packages that should be displayed per page. | 25 | no |
| Work Package Properties | The properties of the Work Packages that will be displayed. | - | no |
| Offset | The offset page that should be used when displaying the work packages. | 0 | no |
| Sort Entries | The property used to sort the displayed work packages. | - | no |
| View as | The displayer that will be used to display the Work Packages. The options are liveDataCards, liveData and workItemsSingle. | livedata | no |
Filtering and sorting for work packages
Filtering and sorting using the OpenProject macro can be done in multiple ways.
In the macro modal, before inserting the macro
When inserting the macro in the page, the filter parameter allows you to filter over the Open Project properties. You create a filter by selecting Add Filter and choosing the property that you want to filter on. Doing that will create a constraint - an operator and the value that the property should match. The operators are of a subset of the ones accepted by the OpenProject. Some properties have pickers implemented for their values to facilitate the filter creation. The properties with pickers are identifier, type, status, project, creator and assignee.
The Sort entries parameter allows you to sort the retrieved work packages based on a property. You can sort the entries by selecting a property that also includes the sorting type. Only the first option from the selected list will be applied to the retrieved work packages.
In the view page, after inserting the macro
The liveData view supports his own filtering. The filtering done in the macro modal was modeled to function similarly to the one provided by the livedata.
The liveData view supports also his own sorting and it can be used to sort the work packages.
In the OpenProject instance
The OpenProject macro can display the Work Packages that match filters or sorting generated from the OpenProject instance.
Create filters or sort the Work Packages
Copy the URL from OpenProject and used it in the macro
Submit and view the work packages in XWiki
Work Packages visualization
By setting the View as parameter, you have multiple ways to display the Work Packages.
LiveData displayer
Work Packages are shown in a table format.
Cards displayer
Work Packages are displayed as cards.
Single item displayer
Only one Work Package is displayed (the first one from the Work Packages list).
Style Synchronization
XWiki tries to keep Work Packages looking similar to how they appear in OpenProject. Styles are automatically updated once a day to match the original appearance. You can also use the Sync Colors button in the OpenProject administration section to update styles immediately.
{{/warning}}
Installation Steps
This paid extensions requires XWiki 14.10 or above. In order to install the extension, follow the next steps inside your XWiki instance (on cloud or on premise).
Navigate to the Extension Manager
In the Applications Panel click on "More Applications..." and then "Install new applications...". Alternatively navigate directly to the Administration and select the "Extensions" section.
Install the Extension
Search for the extension you wish to install and use the Install button to install it.
Get a License
Navigate to the "Licenses" section of the Administration, fill your details, look for the extension you just installed in the live table and click the buttons to get a trial license or to buy a license.
Install the License
If you have selected a trial license then you're good and there's nothing else to do. Your trial license is automatically installed.
However if you've selected to buy a license you'll be redirected to a page to perform the payment. At the end you need to come back to the "Licenses" administration section and click on the "Check for Updates" button. This will download and apply the license you bought.
Use the Extension
Start using the Extension! Refer to the extension's documentation to know how to use it.
Installing Paid Apps on Subwikis
If you want to install an application on the whole farm (main wiki + subwikis), you can do so directly from the main wiki’s Extension Manager, as seen below:
Extensions can also be installed only on a particular subwiki by global admins. Subwiki admins will not be able to install these extensions due to their limited rights.
Options
The price is per year and varies depending on the support level and the number of users.
| Support / Users | 10 | 25 | 50 | 100 | 250 |
|---|---|---|---|---|---|
| Basic |
Benefits
What do you get when you purchase an XWiki extension?
1/3 years license
By purchasing an XWiki extension license, you ll benefit from it during one or three years, depending on the chosen engagement period.
Free updates
You benefit from all the extension updates during one year. You are always up to date.
Support included
If you are facing an issue, you can reach the XWiki support. Our team is always available to help.
How to Buy
To buy, install this extension from inside your XWiki instance and follow the instructions.
Release notes
v1.0
OpenProject Integration (Pro) initial release.
Extension details
License
- GNU Lesser General Public License 2.1
Sources
Issues
Type
- xar
Developed by
Compatibility
- Requires XWiki 14.10 or above.
Dependencies
- org.xwiki.contrib.oidc:oauth2-client 2.19.1
- com.xwiki.projectmanagement:project-management-openproject-macro 1.0
- org.xwiki.platform:xwiki-platform-administration-ui 14.10.2
- org.xwiki.platform:xwiki-platform-localization-script 14.10.2
- org.xwiki.platform:xwiki-platform-csrf 14.10.2
- org.xwiki.platform:xwiki-platform-query-manager 14.10.2
- org.xwiki.platform:xwiki-platform-scheduler-ui 14.10.2
- org.xwiki.platform:xwiki-platform-ckeditor-ui 14.10.2
- org.xwiki.platform:xwiki-platform-rendering-macro-velocity 14.10.2
- org.xwiki.rendering:xwiki-rendering-macro-html 14.10.2
- org.xwiki.platform:xwiki-platform-search-solr-ui 14.10.2
- org.xwiki.platform:xwiki-platform-extension-script 14.10.2
- org.xwiki.platform:xwiki-platform-icon-script 14.10.2