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 |
XWiki SAS public extension which depends on xwiki-platform
Setup an Open Project 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 Open Project 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.
Use the Open Project macro
The Open Project macro will allow you to display workpackages retrieved from the configured Open Project instances. You can either create your own filter or paste in an open project url.
| Name | Description | Default | Required |
|---|---|---|---|
| instance | The name of the Open Project instance that was configured in the administration section. | - | 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 |
| identifier | An Open Project url identifying a work package or a filtered list of work packages. | - | no |
| limit | How many work packages should be displayed per page. | 5 | no |
| offset | The offset page that should be used when displaying the work packages. | 0 | no |
| sort | The properties that should used to sort the displayed work packages. | - | no |
| workItemsDisplayer | The displayer that will be used to render the work packages. The options are "liveDataCards", "liveData" and "workItemsSingle", which displays a single work package (the first result of the query) in an expanded manner. | liveData | 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 over the Open Project properties 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 Open Project. 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 Open Project instance
The open project macro can display the work packages that match a filter generated from the Open Project instance.
Create the filters
Copy the URL from Open Project and user it in the macro
View the macros in XWiki
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.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