App Registry

Abstract

The app-registry service is the single point where all apps register themselves and their respective supported mime types.

Administrators can set default applications on a per MIME type basis and also allow the creation of new files for certain MIME types. This per MIME type configuration also features a description, file extension option and an icon.

MIME Type Configuration / Creation Allow List
- MIME Type Configuration
App Drivers
- CS3org WOPI Server App Driver
- App Provider Configuration
Endpoint Access
Example Yaml Config

MIME Type Configuration / Creation Allow List

The apps will register their supported MIME types automatically, so that users can open supported files with them.

Administrators can set default applications for each MIME type and also allow the creation of new files for certain mime types. This, per MIME type configuration, also features a description, file extension option and an icon.

MIME Type Configuration

Modifing the MIME type config can only be achieved via a yaml configuration. Using environment variables is not possible. For an example, see the ocis_full/config/ocis/app-registry.yaml at docker-compose example. The following is a brief structure and a field description:

Structure

app_registry:
  mimetypes:
  - mime_type: application/vnd.oasis.opendocument.spreadsheet
    extension: ods
    name: OpenSpreadsheet
    description: OpenDocument spreadsheet document
    icon: https://some-website.test/opendocument-spreadsheet-icon.png
    default_app: Collabora
    allow_creation: true
  - mime_type: ...

Fields

mime_type
The MIME type you want to configure.
extension
The file extension to be used for new files.
name
The name of the file / MIME type.
description
The human-readable description of the file / MIME type.
icon
The URL to an icon which should be used for that MIME type.
default_app
The name of the default app which opens this MIME type if the user doesn’t specify one.
allow_creation
Whether a user should be able to create new files of that MIME type (true or false).

App Drivers

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 Infinite Scale by default. It needs at least one WOPI-compliant app like Collabora, OnlyOffice or the Microsoft Online Server or a CS3org WOPI bridge supported app like CodiMD or Etherpad and the CS3org WOPI server.

App Provider Configuration

The configuration of the actual app provider in a docker-compose example can be found in the full ocis-wopi example directory especially in the config sections ocis-appprovider-collabora and ocis-appprovider-onlyoffice.

Endpoint Access

Listing available apps and mime types

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.

Endpoint: specified in the capabilities in apps_url, currently /app/list

Method: HTTP GET

Authentication: None

Request example:

curl 'https://ocis.test/app/list'

Response example:

HTTP status code: 200

{
  "mime-types": [
    {
      "mime_type": "application/pdf",
      "ext": "pdf",
      "app_providers": [
        {
          "name": "OnlyOffice",
          "icon": "https://some-website.test/onlyoffice-pdf-icon.png"
        }
      ],
      "name": "PDF",
      "description": "PDF document"
    },
    {
      "mime_type": "application/vnd.oasis.opendocument.text",
      "ext": "odt",
      "app_providers": [
        {
          "name": "Collabora",
          "icon": "https://some-website.test/collabora-odt-icon.png"
        },
        {
          "name": "OnlyOffice",
          "icon": "https://some-website.test/onlyoffice-odt-icon.png"
        }
      ],
      "name": "OpenDocument",
      "icon": "https://some-website.test/opendocument-text-icon.png",
      "description": "OpenDocument text document",
      "allow_creation": true,
      "default_application": "Collabora"
    },
    {
      "mime_type": "text/markdown",
      "ext": "md",
      "app_providers": [
        {
          "name": "CodiMD",
          "icon": "https://some-website.test/codimd-md-icon.png"
        }
      ],
      "name": "Markdown file",
      "description": "Markdown file",
      "allow_creation": true,
      "default_application": "CodiMD"
    },
    {
      "mime_type": "application/vnd.ms-word.document.macroenabled.12",
      "app_providers": [
        {
          "name": "Collabora",
          "icon": "https://some-website.test/collabora-word-icon.png"
        },
        {
          "name": "OnlyOffice",
          "icon": "https://some-website.test/onlyoffice-word-icon.png"
        }
      ]
    },
    {
      "mime_type": "application/vnd.ms-powerpoint.template.macroenabled.12",
      "app_providers": [
        {
          "name": "Collabora",
          "icon": "https://some-website.test/collabora-powerpoint-icon.png"
        }
      ]
    }
  ]
}

Open a File With ownCloud Web

Endpoint: specified in the capabilities in open_web_url, currently /app/open-with-web

Method: HTTP POST

Authentication (one of them):

Authorization header with OIDC Bearer token for authenticated users or basic auth credentials (if enabled in oCIS)
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

Request examples:

curl -X POST 'https://ocis.test/app/open-with-web?file_id=ZmlsZTppZAo='

curl -X POST 'https://ocis.test/app/open-with-web?file_id=ZmlsZTppZAo=&app_name=Collabora'

Response examples:

The URI from the response JSON is intended to be opened with a GET request in a browser. If the user has not yet a session in the browser, a login flow is handled by ownCloud Web.

HTTP status code: 200

{
  "uri": "https://....."
}

Example responses (error case):

See error cases for Open a file with the app provider

Open a File With the App Provider

Endpoint: specified in the capabilities in open_url, currently /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)
lang (optional)
- default (not given): default language of the application (which might maybe use the browser language)
- possible value is any ISO 639-1 language code. Examples:
  - de
  - en
  - es
  - …

Request examples:

curl -X POST 'https://ocis.test/app/open?file_id=ZmlsZTppZAo='

curl -X POST 'https://ocis.test/app/open?file_id=ZmlsZTppZAo=&lang=de'

curl -X POST '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 -X POST 'https://ocis.test/app/open?file_id=ZmlsZTppZAo=&app_name=Collabora&view_mode=write'

Response examples:

All apps are expected to be opened in an iframe 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:

HTTP status code: 200

{
  "app_url": "https://.....",
  "method": "POST",
  "form_parameters": {
    "access_token": "eyJ0...",
    "access_token_ttl": "1634300912000",
    "arbitrary_param": "lorem-ipsum"
  }
}

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:

HTTP status code: 200

{
  "app_url": "https://...",
  "method": "GET",
  "headers": {
    "access_token": "eyJ0e...",
    "access_token_ttl": "1634300912000",
    "arbitrary_header": "lorem-ipsum"
  }
}

Example responses (error case):

missing file_id

HTTP status code: 400

{
  "code": "INVALID_PARAMETER",
  "message": "missing file ID"
}

wrong view_mode

HTTP status code: 400

{
  "code": "INVALID_PARAMETER",
  "message": "invalid view mode"
}

unknown app_name

HTTP status code: 404

{
  "code": "RESOURCE_NOT_FOUND",
  "message": "error: not found: app 'Collabora' not found"
}

wrong / invalid file id

HTTP status code: 400

{
  "code": "INVALID_PARAMETER",
  "message": "invalid file ID"
}

file id does not point to a file

HTTP status code: 400

{
  "code": "INVALID_PARAMETER",
  "message": "the given file id does not point to a file"
}

file does not exist / unauthorized to open the file

HTTP status code: 404

{
  "code": "RESOURCE_NOT_FOUND",
  "message": "file does not exist"
}

invalid language code

HTTP status code: 400

{
  "code": "INVALID_PARAMETER",
  "message": "lang parameter does not contain a valid ISO 639-1 language code"
}

Creating a File With the App Provider

Endpoint: specified in the capabilities in new_file_url, currently /app/new

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:

parent_container_id (mandatory): ID of the folder in which the file will be created
filename (mandatory): name of the new file
template (optional): not yet implemented

Request examples:

curl -X POST 'https://ocis.test/app/new?parent_container_id=c2lkOmNpZAo=&filename=test.odt'

Response example:

You will receive a file id of the freshly created file, which you can use to open the file in an editor.

{
  "file_id": "ZmlsZTppZAo="
}

Example responses (error case):

missing parent_container_id

HTTP status code: 400

{
  "code": "INVALID_PARAMETER",
  "message": "missing parent container ID"
}

missing filename

HTTP status code: 400

{
  "code": "INVALID_PARAMETER",
  "message": "missing filename"
}

parent container not found

HTTP status code: 404

{
  "code": "RESOURCE_NOT_FOUND",
  "message": "the parent container is not accessible or does not exist"
}

parent_container_id does not point to a container

HTTP status code: 400

{
  "code": "INVALID_PARAMETER",
  "message": "the parent container id does not point to a container"
}

filename is invalid (e.g. includes a path segment)

HTTP status code: 400

{
  "code": "INVALID_PARAMETER",
  "message": "the filename must not contain a path segment"
}

file already exists

HTTP status code: 403

{
  "code": "RESOURCE_ALREADY_EXISTS",
  "message": "the file already exists"
}

Example Yaml Config

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115


# Autogenerated
# Filename: app-registry-config-example.yaml

tracing:
  enabled: false
  type: ""
  endpoint: ""
  collector: ""
log:
  level: ""
  pretty: false
  color: false
  file: ""
debug:
  addr: 127.0.0.1:9243
  token: ""
  pprof: false
  zpages: false
grpc:
  addr: 127.0.0.1:9242
  tls: null
  protocol: tcp
token_manager:
  jwt_secret: ""
reva:
  address: com.owncloud.api.gateway
  tls:
    mode: ""
    cacert: ""
app_registry:
  mimetypes:
  - mime_type: application/pdf
    extension: pdf
    name: PDF
    description: PDF document
    icon: ""
    default_app: ""
    allow_creation: false
  - mime_type: application/vnd.oasis.opendocument.text
    extension: odt
    name: OpenDocument
    description: OpenDocument text document
    icon: ""
    default_app: ""
    allow_creation: true
  - mime_type: application/vnd.oasis.opendocument.spreadsheet
    extension: ods
    name: OpenSpreadsheet
    description: OpenDocument spreadsheet document
    icon: ""
    default_app: ""
    allow_creation: true
  - mime_type: application/vnd.oasis.opendocument.presentation
    extension: odp
    name: OpenPresentation
    description: OpenDocument presentation document
    icon: ""
    default_app: ""
    allow_creation: true
  - mime_type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
    extension: docx
    name: Microsoft Word
    description: Microsoft Word document
    icon: ""
    default_app: ""
    allow_creation: true
  - mime_type: application/vnd.openxmlformats-officedocument.wordprocessingml.form
    extension: docxf
    name: Form Document
    description: Form Document
    icon: ""
    default_app: ""
    allow_creation: true
  - mime_type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
    extension: xlsx
    name: Microsoft Excel
    description: Microsoft Excel document
    icon: ""
    default_app: ""
    allow_creation: true
  - mime_type: application/vnd.openxmlformats-officedocument.presentationml.presentation
    extension: pptx
    name: Microsoft PowerPoint
    description: Microsoft PowerPoint document
    icon: ""
    default_app: ""
    allow_creation: true
  - mime_type: application/vnd.jupyter
    extension: ipynb
    name: Jupyter Notebook
    description: Jupyter Notebook
    icon: ""
    default_app: ""
    allow_creation: false
  - mime_type: text/markdown
    extension: md
    name: Markdown file
    description: Markdown file
    icon: ""
    default_app: ""
    allow_creation: true
  - mime_type: application/compressed-markdown
    extension: zmd
    name: Compressed markdown file
    description: Compressed markdown file
    icon: ""
    default_app: ""
    allow_creation: false
  - mime_type: application/vnd.geogebra.slides
    extension: ggs
    name: GeoGebra Slides
    description: GeoGebra Slides
    icon: ""
    default_app: ""
    allow_creation: false

Environment Variables

Name	Type	Default Value	Description
OCIS_TRACING_ENABLED APP_REGISTRY_TRACING_ENABLED	bool	false	Activates tracing.
OCIS_TRACING_TYPE APP_REGISTRY_TRACING_TYPE	string		The type of tracing. Defaults to ‘’, which is the same as ‘jaeger’. Allowed tracing types are ‘jaeger’ and ’’ as of now.
OCIS_TRACING_ENDPOINT APP_REGISTRY_TRACING_ENDPOINT	string		The endpoint of the tracing agent.
OCIS_TRACING_COLLECTOR APP_REGISTRY_TRACING_COLLECTOR	string		The HTTP endpoint for sending spans directly to a collector, i.e. http://jaeger-collector:14268/api/traces. Only used if the tracing endpoint is unset.
OCIS_LOG_LEVEL APP_REGISTRY_LOG_LEVEL	string		The log level. Valid values are: ‘panic’, ‘fatal’, ’error’, ‘warn’, ‘info’, ‘debug’, ’trace’.
OCIS_LOG_PRETTY APP_REGISTRY_LOG_PRETTY	bool	false	Activates pretty log output.
OCIS_LOG_COLOR APP_REGISTRY_LOG_COLOR	bool	false	Activates colorized log output.
OCIS_LOG_FILE APP_REGISTRY_LOG_FILE	string		The path to the log file. Activates logging to this file if set.
APP_REGISTRY_DEBUG_ADDR	string	127.0.0.1:9243	Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.
APP_REGISTRY_DEBUG_TOKEN	string		Token to secure the metrics endpoint.
APP_REGISTRY_DEBUG_PPROF	bool	false	Enables pprof, which can be used for profiling.
APP_REGISTRY_DEBUG_ZPAGES	bool	false	Enables zpages, which can be used for collecting and viewing in-memory traces.
APP_REGISTRY_GRPC_ADDR	string	127.0.0.1:9242	The bind address of the GRPC service.
OCIS_GRPC_PROTOCOL APP_REGISTRY_GRPC_PROTOCOL	string	tcp	The transport protocol of the GRPC service.
OCIS_JWT_SECRET APP_REGISTRY_JWT_SECRET	string		The secret to mint and validate jwt tokens.
OCIS_REVA_GATEWAY	string	com.owncloud.api.gateway	The CS3 gateway endpoint.
OCIS_GRPC_CLIENT_TLS_MODE	string		TLS mode for grpc connection to the go-micro based grpc services. Possible values are ‘off’, ‘insecure’ and ‘on’. ‘off’: disables transport security for the clients. ‘insecure’ allows using transport security, but disables certificate verification (to be used with the autogenerated self-signed certificates). ‘on’ enables transport security, including server certificate verification.
OCIS_GRPC_CLIENT_TLS_CACERT	string		Path/File name for the root CA certificate (in PEM format) used to validate TLS server certificates of the go-micro based grpc services.

App Registry

Abstract

Table of Contents

MIME Type Configuration / Creation Allow List

MIME Type Configuration

App Drivers

CS3org WOPI Server App Driver

App Provider Configuration

Endpoint Access

Listing available apps and mime types

Open a File With ownCloud Web

Open a File With the App Provider

Creating a File With the App Provider

Example Yaml Config

Environment Variables