add more docs

2026-03-03 06:27:17 -05:00 · 2021-10-14 15:14:46 +02:00
parent 4aced88530
commit 4c53ca03e6
1 changed files with 196 additions and 37 deletions
--- a/docs/extensions/storage/apps.md
+++ b/docs/extensions/storage/apps.md
@@ -1,71 +1,229 @@
+---
+title: "Apps"
+date: 2018-05-02T00:00:00+00:00
+weight: 10
+geekdocRepo: https://github.com/owncloud/ocis
+geekdocEditPath: edit/master/docs/extensions/storage
+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 registry

-
-oCIS is all about files. But most of the time you wan to do something with files. Therefore oCIS has an concept about apps, that can handle specific file types, so called mime types.
-
-App registry
 The app registry is the single point where all apps register itself and their supported mime types.

-Mime type configuration / allow list
+### Mime type configuration / allow list
+
 Administrators need to add supported mime types to the mime type configuration, which works like an allow list. Only mime types on this list will be offered by the app registry even if app providers register additional mime types.

 In order to modify the mime type config you need to set STORAGE_APP_REGISTRY_MIMETYPES_JSON=.../mimetypes.json to a valid JSON file with a content like this:

-{
-   "application/vnd.oasis.opendocument.text":{
-      "extension":"odt",
-      "name":"OpenDocument",
-      "description":"OpenDocument text document",
-      "icon":"",
-      "default_app":"Collabora"
-   },
-   "application/vnd.oasis.opendocument.spreadsheet":{
-      "extension":"ods",
-      "name":"OpenSpreadsheet",
-      "description":"OpenDocument spreadsheet document",
-      "icon":"",
-      "default_app":"Collabora"
-   }
-}
+```json
+[
+  {
+    "mime_type": "application/vnd.oasis.opendocument.text",
+    "extension": "odt",
+    "name": "OpenDocument",
+    "description": "OpenDocument text document",
+    "icon": "",
+    "default_app": "Collabora"
+  },
+  {
+    "mime_type": "application/vnd.oasis.opendocument.spreadsheet",
+    "extension": "ods",
+    "name": "OpenSpreadsheet",
+    "description": "OpenDocument spreadsheet document",
+    "icon": "",
+    "default_app": "Collabora"
+  }
+]
+```
+
 Please add all mime types you would like use with apps. You also can configure, which application should be treated as a default app for a certain mime type by setting the app provider name in default_app.

-Listing available mime types / apps
-/app/list
+### Listing available mime types / apps

+#### /app/list
+
+Method: HTTP GET
+
+Authentication: None
+
+Result:
+
+```json
 {
  "mime-types": [
    {
-      "mime_type": "application/vnd.oasis.opendocument.spreadsheet",
-      "ext": "ods",
+      "mime_type": "application/pdf",
+      "ext": "pdf",
      "app_providers": [
        {
-          "name": "Collabora",
-          "icon": "https://www.collaboraoffice.com/wp-content/uploads/2019/01/CP-icon.png"
+          "name": "OnlyOffice",
+          "icon": "https://www.pikpng.com/pngl/m/343-3435764_onlyoffice-desktop-editors-onlyoffice-logo-clipart.png"
        }
      ],
-      "name": "OpenSpreadsheet",
-      "description": "OpenDocument spreadsheet document"
+      "name": "PDF",
+      "description": "PDF document"
    },
    {
-      "mime_type": "application/vnd.oasis.opendocument.presentation",
-      "ext": "odp",
+      "mime_type": "application/vnd.oasis.opendocument.text",
+      "ext": "odt",
+      "app_providers": [
+        {
+          "name": "Collabora",
+          "icon": "https://www.collaboraoffice.com/wp-content/uploads/2019/01/CP-icon.png"
+        },
+        {
+          "name": "OnlyOffice",
+          "icon": "https://www.pikpng.com/pngl/m/343-3435764_onlyoffice-desktop-editors-onlyoffice-logo-clipart.png"
+        }
+      ],
+      "name": "OpenDocument",
+      "description": "OpenDocument text document",
+      "allow_creation": true
+    },
+    {
+      "mime_type": "text/markdown",
+      "ext": "md",
+      "app_providers": [
+        {
+          "name": "CodiMD",
+          "icon": "https://avatars.githubusercontent.com/u/67865462?v=4"
+        }
+      ],
+      "name": "Markdown file",
+      "description": "Markdown file",
+      "allow_creation": true
+    },
+    {
+      "mime_type": "application/vnd.ms-word.document.macroenabled.12",
+      "app_providers": [
+        {
+          "name": "Collabora",
+          "icon": "https://www.collaboraoffice.com/wp-content/uploads/2019/01/CP-icon.png"
+        },
+        {
+          "name": "OnlyOffice",
+          "icon": "https://www.pikpng.com/pngl/m/343-3435764_onlyoffice-desktop-editors-onlyoffice-logo-clipart.png"
+        }
+      ]
+    },
+    {
+      "mime_type": "application/vnd.ms-powerpoint.template.macroenabled.12",
      "app_providers": [
        {
          "name": "Collabora",
          "icon": "https://www.collaboraoffice.com/wp-content/uploads/2019/01/CP-icon.png"
        }
-      ],
-      "name": "OpenPresentation",
-      "description": "OpenDocument presentation document"
+      ]
    }
-/app/open
+  ]
+}
+```
+
+#### /app/open
+
+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:
+
+- `file_id` (mandatory): id of the file to be opened
+- `app_name` (optional)
+  - default (not given): default app for mime type
+  - possible values depend on the app providers for a mimetype from the `/app/open` endpoint
+- `view_mode` (optional)
+  - default (not given): highest possible view mode, depending on the file permissions
+  - possible values:
+    - `write`: user can edit and download in the opening app
+    - `read`: user can view and download from the opening app
+    - `view`: user can view in the opening app (download is not possible)
+
+Examples:
+
+
+``` bash
+curl 'https://ocis.test/app/open?file_id=ZmlsZTppZAo='
+
+curl 'https://ocis.test/app/open?file_id=ZmlsZTppZAo=&app_name=Collabora'
+
+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'
+```
+
+
+Response:
+
+Result:
+
+``` json
+{
+  "app_url": "https://.....",
+  "method": "POST",
+  "form_parameters": {
+    "access_token": "eyJ0...",
+    "access_token_ttl": "1634300912000",
+    "arbitrary_param": "lorem-ipsum"
+  }
+}
+```
+
+``` json
+{
+  "app_url": "https://...",
+  "method": "GET",
+  "headers": {
+    "access_token": "eyJ0e...",
+    "access_token_ttl": "1634300912000",
+    "arbitrary_header": "lorem-ipsum",
+  }
+}
+```
+
+Errors:
+
+- wrong `view_mode`
+``` json
+{
+  "code": "SERVER_ERROR",
+  "message": "Missing or invalid viewmode argument"
+}
+```
+
+- unknown `app_name`
+``` 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

-App provider / drivers
 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.

-Here is a closer look at the configuration of the actual app provider:
+Here is a closer look at the configuration of the actual app provider in a docker-compose example:
+
+```yaml
+services:
+  ocis: ...

  ocis-appdriver-collabora:
    image: owncloud/ocis:latest
@@ -81,3 +239,4 @@ Here is a closer look at the configuration of the actual app provider:
      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
+```