OpenProject Integration (Pro)
OpenProject 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.
- Setup an OpenProject connection in XWiki
- Syncing the styling between OpenProject and XWiki
- OpenProject macro
- Create work packages from XWiki into OpenProject
- OpenProject Chart Macro
- OpenProject Calendar macro
- OpenProject Dashboard
- OpenProject dashboard and parameters
- Using the dashboard selectors with macros
- New OpenProject macros introduced for OpenProject Dashboard
- Project Management Relations
- Create OpenProject connected space
Setup an OpenProject connection in XWiki
In order to establish a connection between OpenProject and XWiki, follow the steps below:
Configure an OAuth Application in your OpenProject Instance
To configure the 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. You should fill in the information only in the first part of the form, ignoring the Client credentials section. 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.
Configure an OpenProject Instance 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.
You can Edit or Delete any connection at any time using the Actions in the connections table. If the connection is not available anymore (the current connection expired), you can use the third action(TODO: change the third action name) in order to reconnect.
Syncing the styling between OpenProject and XWiki
XWiki will try to display certain properties of the workpackages retrieved from OpenProject in a similar manner to how they looked in OpenProject. In order to do this, a job is scheduled to sync the styles once per day.
The job will run with the rights of the last user that created or edited an OpenProject instance. In order for the user to be authorized, they need to either insert an openproject macro in a xwiki page or view a page that contains the said macro. Alternatively, the admin can see whether they have been authorized to the configured OpenProject instances using the livedata displayed in the Administration section.
OpenProject macro
The OpenProject macro will allow you to display workpackages retrieved from the configured OpenProject instances. You can either create your own filter or paste in an OpenProject URL.
| Name | Description | Default | Required |
|---|---|---|---|
| OpenProject Instance | The name of the OpenProject instance to use for this filter. Configurable in the administration section. | - | yes |
| Description | A description of the resulting Live Data table or card view of the filtered list of work packages. | - | no |
| Filters | The filters that will be applied to the displayed work items. The filter value can be constructed in an user-friendly manner using the macro modal. The raw data that it expects is a json. i.e. {"query":{"filters":[{"property":"startDate","constraints":[{"operator":"t","value":""}]}]}} | - | no |
| Work package(s) identifier | An OpenProject URL identifying a work package or a filtered list of work packages. | - | no |
| Limit | How many work packages should be displayed per page. | 25 | no |
| Offset | The offset page that should be used when displaying the work packages. | 0 | no |
| Work package properties | The properties that will be displayed for each work package, in columns for the Live Data table view. | ID, Type, Subject, Description, Start Date, Assignee, Actions | no |
| Sort entries | The properties that should used to sort the displayed work packages. | - | no |
| View as | The displayer that will be used to render the work packages. The options are "Live Data table", "Cards" and "Single item" / "Single item inline", which displays a single work package (the first result of the query) in an expanded manner / inline. | Live Data table | no |
Filtering for work packages
Filtering using the OpenProject macro can be done in multiple scenarios.
In the macro modal - before inserting the macro
When inserting the macro in the page, the filter parameter allows you to filter the OpenProject work packages in an user friendly manner. 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.
In the view page - after inserting the macro
The liveData displayer supports filtering. The filtering done in the macro modal was modeled to function similarly to the one provided by the livedata.
In the OpenProject instance
The OpenProject macro can display the work packages that match a filter generated from the OpenProject instance.
Create the filters
Copy the URL from OpenProject and user it in the macro
View the work packages in XWiki
Create work packages from XWiki into OpenProject
OpenProject Create work packages macro
You can create Work Packages using the OpenProject Create Work Package macro. This macro can be inserted into any XWiki page from edit mode.
Create work packages macro parameters
| Parameter | Description | Required | Default |
|---|---|---|---|
| Connection | The name of the OpenProject instance to use for this filter. Configurable in the administration section. | Required | first connection |
| Project | One of the projects defined in the OpenProject instance. | Required | empty / Parent Project if filled in Relations |
| Parent | The parent work package. If specified, the new work package will be created as a child of this work package. | Optional | empty / Parent Work package if filled in Relations |
| Subject | The subject of the work package to be created. | Required | empty |
| Description | A detailed description of the work package. | Optional | empty |
| Type | The type of the work package, selected from the project types defined in the OpenProject instance. | Optional | The default value defined in the OpenProject instance |
| Priority | The priority level assigned to the work package, selected from the project priorities defined in the OpenProject instance. | Optional | The default value defined in the OpenProject instance |
| Status | The initial status of the work package, selected from the project statuses defined in the OpenProject instance. | Optional | The default value defined in the OpenProject instance |
| Assignee | The user assigned to the work package, selected from the project users available, defined in the OpenProject instance. | Optional | empty |
| Start date | The planned start date of the work package. | Optional | empty |
| Finish date | The planned finish date of the work package. | Optional | empty |
Create work packages from macro display
After filling in the required macro parameters, the newly created Work Package (in the OpenProject instance) will be displayed on the page using the OpenProject macro, with the Single inline item displayer option.
Create work packages from highlighted text in the documentation
You can select any text in the XWiki instance and, by choosing OpenProject → Create Work Package, create a work package whose subject is automatically populated with the selected text. The parameters you can define are the same as those for the OpenProject Create Work Package macro.
Create work packages from highlight display
The created work package gets inserted as an inline link.
Loading the video player...
Create multiple work packages from highlighted rows or cells in a documentation table
You can create multiple work packages at once by selecting rows or cells from a documentation table. Each selected row is processed as input for ticket creation, allowing table content to be quickly transformed into multiple OpenProject work packages.
This type of creation supports an extra parameter, OpenProject Mapping. It allows you to define mappings between table columns and the parameters required for a work package, giving you control over the meaning of the table columns. If the table has a defined header, the columns will take the name of each column; otherwise, they will be named Col1, Col2, etc.
After the creation, the created Work Packages will be displayed on the page using the OpenProject macro, with the Single inline item displayer option as follows:
OpenProject Chart Macro
| Parameter | Description | Value | Default |
|---|---|---|---|
| Connection | The name of the OpenProject instance to use for this filter. Configurable in the administration section. | string | first connection |
| Dataset Labels | A JSON list of strings representing the labels associated to each filter (each dataset). When displaying the results of a given filter, the chart should associate the provided label to it. The WYSIWYG macro modal offers a user friendly UI for creating the labels. | JSON | empty |
| Filters | A JSON list of filters matching the Livedata configuration specification. The WYSIWYG macro modal offers a user friendly UI for building your filters for each dataset. | JSON | empty |
| Limit | The limit that will be set on the queried filters. If we filter for the work packages created today and set the limit to 10, only 10 work packages matching the filter will be returned. | Number | 100 |
| Offset | The offset that is applied to the result of the filters. If we filter for the work packages created today and set the offset to 5, we will get the result starting from the fifth entry. | Number | 0 |
| Work package property | A property of a work package i.e. status. The chart will group the filter results on the given property. For example, if you select the status property, it's expected that a chart of all the status values will be displayed, counting the number of work packages per value. | String | status |
| Chart type | The type of chart that should be displayed. In WYSIWYG macro modal, the possible values will be dynamically displayed from the existing implementations. The value represents the id of the chart implementation. | String | bar |
| Chart type Parameters | A JSON serialization of the chart type parameters. Each chart type will accepts it's own custom parameters. In WYSIWYG, the parameters will be displayed in a user friendly manner. | JSON | empty |
ChartJS-based displayers
Currently, the Open Project Chart macro offers 4 chart type implementations, all based on the ChartJS library. The four chart types are BAR, PIE, DOUGHNUT and LINE.
All these chart types support two additional parameters:
- metric: this parameter supports either count or accumulate value. By default, the count value is used. This parameter defines what metric should be used when aggregating the results of the filters. When count value is used, the chart that has the `create date` property selected, will count the number of work packages that have the creation date inside a given period (i.e. monthly). If accumulate is used, each month will represent the number of work packages created in a given month and before that.
- period: this parameter supports one of the following values DAILY, MONTHLY, YEARLY, HOURLY. By default, the MONTHLY value is used. The value is taken into consideration when the chart property is of a DATE type. i.e. creation date. If, for example, the DAILY parameter is used, the results for the datasets will be grouped per days.
OpenProject Charts example
1. Select the desired OpenProject instance and create two labels (by clicking 'Add new label')
2. Create the desired filters (datasets) by clicking `Add new dataset`, selecting the property you want to filter on, select the operator that you want to apply on the property and the value/s (some operators dont require a value)
3. Set the limit, offset. Select the property of interest, in our case "created at". Select the chart type we want to see. Set the aggregation method and period.
4. View the result
Other examples:
OpenProject Calendar macro
The OpenProject calendar macro will allow you to display work packages, sprints and versions retrieved from the configured OpenProject instances.
| Name | Description | Default | Required |
|---|---|---|---|
| Connection | The name of the OpenProject instance to use for this filter. Configurable in the administration section. | first connection | yes |
| Filters | The filters that will be applied to the displayed work items. The filter value can be constructed in an user-friendly manner using the macro modal. The raw data that it expects is a json. i.e. {"query":{"filters":[{"property":"startDate","constraints":[{"operator":"t","value":""}]}]}} | - | no |
| Default view | The initial layout of the calendar on load. | Month | no |
| Starting day | The first day of the week. | Sunday | no |
| Limit | How many events should be pulled from OpenProject. | 25 | no |
| Time interval | The time interval displayed in the agenda views. | 08:00 - 18:00 | no |
Types | Select the event types to be displayed in the calendar. The options are Work Package, Sprint and version. | Work package | no |
| Sprints color | Select the color of sprints to display in the calendar. Only displayed if the Sprint type is selected. | - | no |
| Versions color | Select the color of versions to display in the calendar. Only displayed if the Version type is selected. | - | no |
Default views
The default views in the following order: Month, Agenda Week, Agenda Day, Basic Week, Basic Day.
Filtering for work packages
When inserting the calendar macro in the page, the filter parameter allows you to filter over the OpenProject properties of work packages in a user friendly manner. 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 ID, type, status, project, author and assignee.
Selecting different event types
You can display work packages, sprints and versions events in the calendar. The work packages color will have the same color scheme as the work package type from the configured OpenProject instance. Selecting Version and Sprint event types will also show the color pickers for the associated event.
Interacting with events
Viewing an event details
You can view some minimal details regarding any event by simply hovering over it. This will highlight the current event status and description.
Work packages interaction
In addition to the minimal hovering information, you can click on a work package to display a modal with the event details.
From this modal, you can further edit the properties of the work package:
OpenProject Dashboard
OpenProject dashboard and parameters
The OpenProject Dashboard (<yourwiki>OpenProject.WebHome) is a page that aggregates information from your OpenProject instance. At the top of the page, two selectors let you control what all the macros on the page display:
- Connection: the OpenProject instance to use.
- Project: a project within the selected instance.
Changing either selector immediately re-points every macro on the page that is configured to follow it (has "Use selected dashboard instance" or "Use selected dashboard project" selected).
Using the dashboard selectors with macros
If OpenProject macros are used on the main OpenProject dashboard page, both the instance parameter and the project parameter will include the "Use selected dashboard connection" and "Use selected dashboard project" options, respectively. Selecting these options instructs the macro to use the values currently selected in the corresponding dashboard selector.
If a macro on the dashboard page has specific values explicitly selected for either of these two parameters, the dashboard's connection and project selectors will not override those values.
New OpenProject macros introduced for OpenProject Dashboard
OpenProject Assigned to Me Macro
Retrieves the work packages from OpenProject that are assigned to the current user and displays them in a table.
OpenProject Assigned to Me Macro Parameters
The OpenProject Assigned to Me macro can be configured using a set of parameters. These parameters allow you to customize the macro’s behavior depending on the needs. The currently available parameters are described below:
| Name | Description | Required | Default |
|---|---|---|---|
| OpenProject instance | The OpenProject instance from which to retrieve the work items. | Yes | - |
| View as | How the work packages are displayed, similar to OpenProject macro View as parameter. | No | LiveData |
| Work Package Properties | The columns shown in the table. | No | - |
| Sort entries | How the displayed work packages are ordered. | No | - |
| Limit | The maximum number of work items to display. | No | - |
| Offset | The index of the first work item to show. | No | 0 |
OpenProject Assigned to Me Macro display
OpenProject News Macro
Retrieves and displays the latest news entries from an OpenProject instance.
OpenProject Project News Macro Parameters
The OpenProject Project News macro can be configured using a set of parameters. These parameters allow you to customize the macro's behavior depending on the needs. The currently available parameters are described below:
| Name | Description | Required | Default |
|---|---|---|---|
| OpenProject instance | The OpenProject instance from which to retrieve the news. | Yes | - |
| Project | Filter news by a specific project. Leave empty to show news from all projects. | No | - |
| Number of News Items | The maximum number of news items to display. | No | 5 |
OpenProject Project News Macro display
OpenProject Project Details Macro
Displays the details of a single project from an OpenProject instance, including its name, description, status, and creation date.
OpenProject Project Details Macro Parameters
The OpenProject Project Details macro can be configured using a set of parameters. These parameters allow you to customize the macro's behavior depending on the needs. The currently available parameters are described below:
| Name | Description | Required | Default |
|---|---|---|---|
| OpenProject instance | The OpenProject instance from which to retrieve the project. | Yes | - |
| Project | The project to display. | Yes | - |
OpenProject Project Details Macro display
OpenProject Project Members Macro
Displays the members of a specific project from an OpenProject instance, grouped by their role.
OpenProject Project Members Macro Parameters
The OpenProject Project Members macro can be configured using a set of parameters. These parameters allow you to customize the macro's behavior depending on the needs. The currently available parameters are described below:
| Name | Description | Required | Default |
|---|---|---|---|
| OpenProject instance | The OpenProject instance from which to retrieve the project members. | Yes | - |
| Project | The project whose members will be displayed. | Yes | - |
| Count | The maximum number of members to retrieve. | No | 25 |
OpenProject Project Members Macro display
OpenProject Spent Time Macro
Displays the spent time logged on an OpenProject instance, grouped by date with per-day and total hours.
OpenProject Spent Time Macro Parameters
The OpenProject Spent Time macro can be configured using a set of parameters. These parameters allow you to customize the macro's behavior depending on the needs. The currently available parameters are described below:
| Name | Description | Required | Default |
|---|---|---|---|
| OpenProject instance | The OpenProject instance from which to retrieve the time entries. | Yes | - |
| Project | The project whose time entries will be displayed. Leave empty to include all projects. | No | - |
| Count | The maximum number of time entries to retrieve. | No | 25 |
| Days | The number of past days to include. Set to 0 to show all entries without a date filter. | No | 7 |
OpenProject Spent Time Macro display
OpenProject Subprojects Macro
Displays the subprojects of a specific project from an OpenProject instance.
OpenProject Subprojects Macro Parameters
The OpenProject Subprojects macro can be configured using a set of parameters. These parameters allow you to customize the macro's behavior depending on the needs. The currently available parameters are described below:
| Name | Description | Required | Default |
|---|---|---|---|
| OpenProject instance | The OpenProject instance from which to retrieve the subprojects. | Yes | - |
| Project | The project whose subprojects will be displayed. | Yes | - |
| Count | The maximum number of subprojects to display. | No | 25 |
OpenProject Subprojects display
Project Management Relations
Parent Project and Work Package
In order to link OpenProject projects and work packages to XWiki spaces, you can setup relations between the two software as follows.
1. Go to `More Actions` of your page and select `Project Management Relations`
2. Select the Project Management that you integrated with. In our case `OpenProject` and click `Add new relation`
3. Click on the edit pen next to the `Select the OpenProject instance` and select the connection to your open project instance. Afterwards, click on the checkmark.
4. Then, in a similar manner, you can choose the project and work package that you want to link with.
5. Once you created the relation, it will also be visible in the `Project Management Relations` tab at the bottom of your page
Loading the video player...
Mentions
When you create a work package from XWiki into OpenProject and when you mention an XWiki page on an OpenProject work package, a special type of relation called "Mention" is created. All mentioned OpenProject work packages appear in XWiki in the dedicated "Project Management Relations" tab.
Create OpenProject connected space
If you wish to create a documentation space already connected to an OpenProject instance, project and work package, you can do so by selecting the "OpenProject Space" template.
1. Select this template upon page creation:
2. Fill in the OpenProject connection, project and work package
3. You will obtain three created pages, one Project Homepage, one Specifications page, and one Meeting notes template, with OpenProject macros prefilled.
Loading the video player...
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
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.21.1
- com.xwiki.projectmanagement:project-management-openproject-macro 1.2.0
- com.xwiki.projectmanagement:project-management-relations-ui 1.2.0
- com.xwiki.licensing:application-licensing-licensor-api 1.32.3
- org.xwiki.platform:xwiki-platform-administration-ui 15.10
- org.xwiki.platform:xwiki-platform-localization-script 15.10
- org.xwiki.platform:xwiki-platform-csrf 15.10
- org.xwiki.platform:xwiki-platform-query-manager 15.10
- org.xwiki.platform:xwiki-platform-scheduler-ui 15.10
- org.xwiki.platform:xwiki-platform-ckeditor-ui 15.10
- org.xwiki.platform:xwiki-platform-rendering-macro-velocity 15.10
- org.xwiki.rendering:xwiki-rendering-macro-html 15.10
- org.xwiki.platform:xwiki-platform-search-solr-ui 15.10
- org.xwiki.platform:xwiki-platform-extension-script 15.10
- org.xwiki.platform:xwiki-platform-icon-script 15.10
- com.xwiki.urlshortener:application-urlshortener-ui 1.3.4