From 2d19cd93bd1d3ffa4f8243db508a1a6f57fb2a34 Mon Sep 17 00:00:00 2001 From: Willy Kloucek Date: Tue, 26 Oct 2021 15:09:29 +0200 Subject: [PATCH] update docs --- docs/extensions/storage/apps.md | 178 ++++++++++++++++++++------------ 1 file changed, 112 insertions(+), 66 deletions(-) diff --git a/docs/extensions/storage/apps.md b/docs/extensions/storage/apps.md index aae274c6d..959318647 100644 --- a/docs/extensions/storage/apps.md +++ b/docs/extensions/storage/apps.md @@ -9,6 +9,33 @@ geekdocFilePath: apps.md oCIS is all about files. But most of the time you want to do something with files. Therefore oCIS has an concept about apps, that can handle specific file types, so called mime types. +## App provider capability + +The capabilities endpoint (eg. `https://localhost:9200/ocs/v1.php/cloud/capabilities?format=json`) gives you following capabilities which are relevant for the app provider: + +```json +{ + "ocs": { + "data": { + "capabilities": { + "files": { + "app_providers": [ + { + "enabled": true, + "version": "1.0.0", + "apps_url": "/app/list", + "open_url": "/app/open" + } + ] + } + } + } + } +} +``` + +Please note that there might be two or more app providers with different versions. This is not be expected to happen on a regular basis. It was designed for a possible migration period for clients when the app provider needs a breaking change. + ## App registry The app registry is the single point where all apps register itself and their supported mime types. @@ -24,11 +51,11 @@ In order to modify the mime type config you need to set `STORAGE_APP_REGISTRY_MI ```json [ { - "mime_type": "application/vnd.oasis.opendocument.text", + "mime_type": "applition/vnd.oasis.opendocument.text", "extension": "odt", "name": "OpenDocument", "description": "OpenDocument text document", - "icon": "", + "icon": "https://some-website.test/opendocument-text-icon.png", "default_app": "Collabora", "allow_creation": true }, @@ -43,25 +70,34 @@ In order to modify the mime type config you need to set `STORAGE_APP_REGISTRY_MI } ] ``` + Fields: - - `mime_type` is the mime type you want to configure - - `extension` is the file extension to be used for new files - - `name` is the name of the file / mime type - - `description` is a human readable description of the file / mime type - - `icon` URL to an icon which should be used for that mime type - - `default_app` name of the default app which opens this mime type when the user doesn't specify one - - `allow_creation` is wether a user should be able to create new file from that mime type (`true` or `false`) +- `mime_type` is the mime type you want to configure +- `extension` is the file extension to be used for new files +- `name` is the name of the file / mime type +- `description` is a human readable description of the file / mime type +- `icon` URL to an icon which should be used for that mime type +- `default_app` name of the default app which opens this mime type when the user doesn't specify one +- `allow_creation` is wether a user should be able to create new file from that mime type (`true` or `false`) -### Listing available mime types / apps +### Listing available apps / mime types -#### /app/list +Clients, for example ownCloud Web, need to offer users the available apps to open files and mime types for new file creation. This information can be obtained from this endpoint. -Method: HTTP GET +**Endpoint**: specified in the capabilities in `apps_url`, currently `/app/list` -Authentication: None +**Method**: HTTP GET -Result: +**Authentication**: None + +**Request example**: + +```bash +curl 'https://ocis.test/app/list' +``` + +**Response example**: ```json { @@ -92,6 +128,7 @@ Result: } ], "name": "OpenDocument", + "icon": "https://some-website.test/opendocument-text-icon.png", "description": "OpenDocument text document", "allow_creation": true }, @@ -134,17 +171,19 @@ Result: } ``` -#### /app/open +### Open a file with the app provider -Method: HTTP POST +**Endpoint**: specified in the capabilities in `open_url`, currently `/app/open` -Authentication (one of them): +**Method**: HTTP POST + +**Authentication** (one of them): - `Authorization` header with OIDC Bearer token for authenticated users or basic auth credentials (if enabled in oCIS) - `Public-Token` header with public link token for public links - `X-Access-Token` header with a REVA token for authenticated users -Query parameters: +**Query parameters**: - `file_id` (mandatory): id of the file to be opened - `app_name` (optional) @@ -157,27 +196,25 @@ Query parameters: - `read`: user can view and download from the opening app - `view`: user can view in the opening app (download is not possible) -Examples: +**Request examples**: +```bash +curl -X POST 'https://ocis.test/app/open?file_id=ZmlsZTppZAo=' -``` bash -curl 'https://ocis.test/app/open?file_id=ZmlsZTppZAo=' +curl -X POST 'https://ocis.test/app/open?file_id=ZmlsZTppZAo=&app_name=Collabora' -curl 'https://ocis.test/app/open?file_id=ZmlsZTppZAo=&app_name=Collabora' +curl -X POST 'https://ocis.test/app/open?file_id=ZmlsZTppZAo=&view_mode=read' -curl 'https://ocis.test/app/open?file_id=ZmlsZTppZAo=&view_mode=read' - -curl 'https://ocis.test/app/open?file_id=ZmlsZTppZAo=&app_name=Collabora&view_mode=write' +curl -X POST 'https://ocis.test/app/open?file_id=ZmlsZTppZAo=&app_name=Collabora&view_mode=write' ``` +**Response examples**: -Response: +All apps are expected to be opened in an iframe and the response will give some parameters for that action. -Apps are expected to be opened in Iframes and the response will give some parameters for that action. +There are apps, which need to be opened in the iframe with a form post. The form post must include all form parameters included in the response. For these apps the response will look like this: -Some apps expect to be opened in the Iframe with a form post. The response will look like this: - -``` json +```json { "app_url": "https://.....", "method": "POST", @@ -189,71 +226,80 @@ Some apps expect to be opened in the Iframe with a form post. The response will } ``` +There are apps, which need to be opened in the iframe with a GET request. The GET request must have set all headers included in the response. For these apps the response will look like this: -Some apps expect to be opened in the Iframe with a GET request and need additional headers to be set: - -``` json +```json { "app_url": "https://...", "method": "GET", "headers": { "access_token": "eyJ0e...", "access_token_ttl": "1634300912000", - "arbitrary_header": "lorem-ipsum", + "arbitrary_header": "lorem-ipsum" } } - ``` -If opening an app fails, you may encounter one of the following errors: +**Example responses (error case)**: - wrong `view_mode` -``` json -{ - "code": "SERVER_ERROR", - "message": "Missing or invalid viewmode argument" -} -``` + + ```json + { + "code": "SERVER_ERROR", + "message": "Missing or invalid viewmode argument" + } + ``` - unknown `app_name` -``` json -{ - "code": "SERVER_ERROR", - "message": "error searching for app provider" -} -``` + + ```json + { + "code": "SERVER_ERROR", + "message": "error searching for app provider" + } + ``` - wrong / invalid file id / unauthorized to open the file -``` json -{ - "code": "SERVER_ERROR", - "message": "error statting file" -} -``` -## App provider / drivers + ```json + { + "code": "SERVER_ERROR", + "message": "error statting file" + } + ``` -WOPI app provider with CS3org WOPI server -You can run an app provider next to your regular oCIS (docker-compose example). Aditionally you need a CS3 WOPI server and Collabora Online instances running. Both can be found in our WOPI deployment example. +## App drivers -Here is a closer look at the configuration of the actual app provider in a docker-compose example: +App drivers represent apps, if the app is not able to register itself. Currently there is only the CS3org WOPI server app driver. + +### CS3org WOPI server app driver + +The CS3org WOPI server app driver is included in oCIS by default. It needs at least one WOPI compliant app (eg. Collabora, OnlyOffice or Microsoft Online Online Server) or a CS3org WOPI bridge supported app (CodiMD or Etherpad) and the CS3org WOPI server. + +Here is a closer look at the configuration of the actual app provider in a docker-compose example (see also [full example](https://github.com/owncloud/ocis/blob/master/deployments/examples/ocis_wopi/docker-compose.yml)): ```yaml services: - ocis: ... + ocis: + image: owncloud/ocis:latest + ... + environment: + ... + STORAGE_GATEWAY_GRPC_ADDR: 0.0.0.0:9142 # make the REVA gateway accessible to the app drivers ocis-appdriver-collabora: image: owncloud/ocis:latest - command: storage-app-provider server + command: storage-app-provider server # start only the app driver environment: - STORAGE_GATEWAY_ENDPOINT: ocis:9142 - APP_PROVIDER_BASIC_EXTERNAL_ADDR: ocis-appdriver-collabora:9164 + STORAGE_GATEWAY_ENDPOINT: ocis:9142 # oCIS gateway endpoint + APP_PROVIDER_BASIC_EXTERNAL_ADDR: ocis-appdriver-collabora:9164 # how oCIS can reach this app driver OCIS_JWT_SECRET: ocis-jwt-secret APP_PROVIDER_DRIVER: wopi - APP_PROVIDER_WOPI_DRIVER_APP_NAME: Collabora - APP_PROVIDER_WOPI_DRIVER_APP_ICON_URI: https://www.collaboraoffice.com/wp-content/uploads/2019/01/CP-icon.png - APP_PROVIDER_WOPI_DRIVER_APP_URL: https://collabora.owncloud.test + APP_PROVIDER_WOPI_DRIVER_APP_NAME: Collabora # will be used as name for this app + APP_PROVIDER_WOPI_DRIVER_APP_ICON_URI: https://www.collaboraoffice.com/wp-content/uploads/2019/01/CP-icon.png # will be used as icon for this app + APP_PROVIDER_WOPI_DRIVER_APP_URL: https://collabora.owncloud.test # endpoint of collabora APP_PROVIDER_WOPI_DRIVER_INSECURE: false APP_PROVIDER_WOPI_DRIVER_IOP_SECRET: wopi-iop-secret - APP_PROVIDER_WOPI_DRIVER_WOPI_URL: https://wopiserver.owncloud.test + APP_PROVIDER_WOPI_DRIVER_WOPI_URL: https://wopiserver.owncloud.test # endpoint of the CS3org WOPI server ```