sheppy/opendesk
1
0
Fork 0
mirror of https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk.git synced 2025-12-07 07:51:38 +01:00
Code Issues Packages Projects Releases Wiki Activity

fix(docu): Update documentation on integration uses cases (#95).

Browse Source
This commit is contained in:
Thorsten Roßner
2024-07-03 09:44:08 +02:00
parent 7239df2ec1
commit 382af1dfb9
2 changed files with 76 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
cspell.json
View File

@@ -69,7 +69,11 @@
"cryptpad", "cryptpad",
"clamav", "clamav",
"templating", "templating",
"localpart" "localpart",
"Addressbooks",
"filestore",
"trashbin",
"bootstrap"
], ],
"ignoreWords": [], "ignoreWords": [],
"import": [] "import": []

103
docs/components.md
View File

@@ -10,11 +10,11 @@ This section covers the internal system requirements as well as external service
<!-- TOC --> <!-- TOC -->
* [Overview](#overview) * [Overview](#overview)
* [Component integration](#component-integration) * [Component integration](#component-integration)
* [Intercom Service (ICS)](#intercom-service-ics) * [Intercom Service / Silent Login](#intercom-service--silent-login)
* [Filepicker](#filepicker) * [Filepicker](#filepicker)
* [Central Navigation](#central-navigation) * [Central Navigation](#central-navigation)
* [(Read \& write) Central contacts](#read--write-central-contacts) * [Central Contacts](#central-contacts)
* [OpenProject file store](#openproject-file-store) * [File Store (OpenProject -\> Nextcloud)](#file-store-openproject---nextcloud)
* [Identity data flows](#identity-data-flows) * [Identity data flows](#identity-data-flows)
* [Provisioning](#provisioning) * [Provisioning](#provisioning)
<!-- TOC --> <!-- TOC -->
@@ -56,58 +56,91 @@ Some use cases require inter component integration.
```mermaid ```mermaid
flowchart TD flowchart TD
OXAppSuiteFrontend-->|SilentLogin, Filepicker, CentralNavigation|IntercomService OX-AppSuite_Frontend-->|Silent Login, Filepicker, Central Navigation|Intercom_Service
Element-->|CentralNavigation|IntercomService Element-->|Silent Login, Central Navigation|Intercom_Service
IntercomService-->|SilentLogin, TokenExchange|IdP Intercom_Service-->|Silent Login, Token Exchange|IdP
IntercomService-->|Filepicker|Nextcloud Intercom_Service-->|Filepicker|Nextcloud
IntercomService-->|CentralNavigation|Portal Intercom_Service-->|Central Navigation|Portal
OXAppSuiteBackend-->|Filepicker|Nextcloud OX-AppSuite_Backend-->|Filepicker|Nextcloud
Nextcloud-->|Central Navigation|Portal Nextcloud-->|Central Navigation|Portal
OpenProject-->|Central Navigation|Portal OpenProject-->|Central Navigation|Portal
OpenProject-->|File store|Nextcloud OpenProject-->|File Store|Nextcloud
XWiki-->|Central Navigation|Portal XWiki-->|Central Navigation|Portal
Nextcloud-->|CentralContacts|OXAppSuiteBackend Nextcloud-->|Central Contacts|OX-AppSuite_Backend
OXAppSuiteFrontend-->|Filepicker|OXAppSuiteBackend OX-AppSuite_Frontend-->|Filepicker|OX-AppSuite_Backend
``` ```
## Intercom Service (ICS) Most details can be found in the upstream documentation that is linked in the respective sections.
The Univention Intercom Service's role is to enable cross-application integration based on browser interaction. ## Intercom Service / Silent Login
Handling authentication when the frontend of an application is using the API from another application is often a
The Intercom Service's role is to enable cross-application integration based on the user's browser interaction as handling
authentication when the frontend of an application has to call the API from another application is often a
challenge. challenge.
For more details on the ICS please refer to its own [doc](./components/intercom-service.md).
To establish a session with the Intercom Service, the application that wants to use the ICS must initiate a silent To establish a session with the Intercom Service an application can use the silent login feature within an iframe.
login.
Currently only OX AppSuite is using the frontend-based integration, and therefore it is right now the only consumer of Currently only OX AppSuite and Element are using the frontend based integration.
the ICS API.
**Links**
- [Intercom Service upstream documentation](https://docs.software-univention.de/intercom-service/latest/index.html).
## Filepicker ## Filepicker
The Nextcloud filepicker which is integrated into the OX AppSuite allows you to add attachments or links to files from The Nextcloud filepicker is integrated into the OX AppSuite supporting the following use cases against the respective openDesk instance's Nextcloud:
and saving attachments to Nextcloud. - Attaching files from Nextcloud to emails.
- Adding links of Nextcloud files to emails.
- Saving attachments from emails into Nextcloud.
- Attaching files from Nextcloud to calendar entries.
The filepicker is using frontend and backend based integration. The filepicker is using frontend and backend based integration:
Frontend-based integration means that OX AppSuite in the browser is communicating with ICS. - For frontend based integration the OX AppSuite frontend uses the Intercom Service.
While using backend-based integration, OX AppSuite middleware is communicating with Nextcloud, which is especially used - Backend based integration is coming from OX AppSuite middleware. The middleware is communicating directly with Nextcloud,
when adding a file to an email or storing a file into Nextcloud. which is used when adding a file to an email or storing a file into Nextcloud, to avoid passing these files through the user's browser.
**Links**
- [OX AppSuite Nextcloud Integration upstream documentation](https://gitlab.open-xchange.com/extensions/nextcloud-integration/-/tree/main/documentation).
## Central Navigation ## Central Navigation
Central navigation is based on an API endpoint in the portal that provides the contents of the portal for a user to Central navigation is based on an API endpoint in the Nubus portal that returns a JSON containing the contents of the portal for
allow components to render the menu showing all available SWP applications for the user. a given user. The response from the API endpoint is used in the openDesk applications to render the central navigation.
## (Read & write) Central contacts The API can be called by
- frontend services through the Intercom Service's `/navigation.json` endpoint or
- backend services directly at the portal's `/univention/portal/navigation.json` endpoint.
Open-Xchange App Suite is used to manage contacts within openDesk. There is an API in the AppSuite that is being used by The central navigation expects the API caller to present a shared secret for authentication and the username for whom the portal
Nextcloud to lookup contacts as well as to create contacts. This is maybe done when a file is shared with a not yet contents should be returned for.
available personal contact.
## OpenProject file store A `curl` based request returning the navigation contents looks like this:
By default, Nextcloud is a configured option for storing attachments in OpenProject. ```
The file store can be enabled on a per-project level in OpenProject's project admin section. curl 'https://portal.<DOMAIN>/univention/portal/navigation.json?base=https%3A//portal.<DOMAIN>&language=de-DE' -u "<USERNAME>:<SHARED_SECRET>"
```
## Central Contacts
OX App Suite is managing contacts in openDesk. Therefore Nextcloud's PHP backend is using the OX AppSuite's middleware Contacts API to
- create a new contact in the user's contacts folder when a file is shared with a yet unknown email address.
- retrieve contacts from the user's contacts folder to support search-as-you-type when starting to share a file.
**Links:**
- Currently used [OX Contacts API (deprecated)](https://documentation.open-xchange.com/components/middleware/http/8/index.html#!Contacts).
- New [OX Addressbooks API](https://documentation.open-xchange.com/components/middleware/http/8/index.html#!Addressbooks) the Central Contacts integration will switch to.
## File Store (OpenProject -> Nextcloud)
While OpenProject allows you to attach files to work packages directly, it is often preferred that the files are
stored within Nextcloud or to link an existing file from your openDesk Nextcloud to a work package.
Therefore openDesk pre-configures the trust between the openDesk instance's OpenProject and Nextcloud during the `openproject-boostrap` deployment step. As prerequisite for that openDesk's Nextcloud contains the `integration_openproject` app.
The file store still needs to be enabled on a per-project level in OpenProject's project admin section.
**Links:**
- [OpenProject's documentation on Nextcloud integration](https://www.openproject.org/docs/system-admin-guide/integrations/nextcloud/)
- [OpenProject Integration Nextcloud app](https://apps.nextcloud.com/apps/integration_openproject)
# Identity data flows # Identity data flows