Open Integration (Plugin) System

[Utzel-Butzel]

This is the first draft for broadening the current plugin system that basically shows any website.

Integration Settings

Native Settings

Rotation, quality, etc.

{
  "orientation": "landscape"
}

JSON Form Elements

Internal native inputs that can be configured via JSON.
Used for simple Text, Number, Select, etc. without any logic.

{
  "properties": {
    "calendars": { "type": "array", "items": { "type": "string" } },
    "timeRangeDays": { "type": "integer", "minimum": 1, "maximum": 60, "default": 7 }
  }
}

Iframe

Custom form areas that are an iFrame (from the external provider).
This could be anything.

{
  "settingsPage": "https://myExampleIntegration.com/settings"
}

Communication is done via postMessage.

App → Plugin

• Current settings:

  {
    "lat": 21.122,
    "lng": 41.33
  }

• Device & app details:

  {
    "deviceId": "21asisaasdjdsajasdj",
    "applanguage": "de-DE"
  }

• Redirect URL (for integrations that need to be displayed in a separate window for security reasons, e.g. OAuth).
  The Integration can open a new window and after successful data gathering it can redirect back to the App where the data is applied.

  {
    "redirectUrl": "https://web.wirewire.de/organizationId/device/deviceId/paperId",
    "tempToken": "tokenToAllowExternalContentViaLink"
  }

  By supplying data to the redirectUrl in combination with the tempToken via GET parameter, you can jump back into the app while updating the user’s settings.

Plugin → App

• JSON Object (can contain form content, etc.)
• Required frame height

Display

The website that will be used to render the content:

{
  "renderPage": "https://myExampleIntegration.com/render"
}

It will get the integration settings via postMessage.

Ideas

Worker

For additional background exchanges?

WebHooks

After registering, the Plugin gets a WebHook URL which allows it to force updates.

Would this work with:

• Google Calendar: ✅ Yes
• NextCloud: ✅ Yes
• HomeAssistant: ❌ No (requires a plugin on the HomeAssistant side to push the content)

Entry point

Each plugin can be installed by simply pointing to an URL with the config.

https://myExampleIntegration.com/config.json

{
  "name": "MyExampleIntegration",
  "version": "1.0.0",
  "description": "An example integration plugin for demonstration purposes.",
  "icon": "https://myExampleIntegration.com/myIcon.png",
  "nativeSettings": {
    "orientation": "landscape",
    "quality": "high"
  },
  "formSchema": {
    "type": "object",
    "properties": {
      "calendars": {
        "type": "array",
        "items": { "type": "string" },
        "description": "List of calendar IDs to sync",
        "required": true
      },
      "timeRangeDays": {
        "type": "integer",
        "minimum": 1,
        "maximum": 60,
        "default": 7,
        "description": "How many days ahead to fetch events"
      }
    },
  },
  "settingsPage": "https://myExampleIntegration.com/settings",
  "renderPage": "https://myExampleIntegration.com/render"
}

Security risks

User needs to trust the integration.
Malicious integration page executes arbitrary JS, tries to break out, steals focus, or initiates drive-by actions.
Everything should lay on a different domain and avoid any CORS.
INVESTIGATE: For Google Calendar the token should probably not be send via postMessage. It would be also stored inside the settings.
TempToken should be short lived (maybe 10 minutes so everyone get's logged in) and single use.

Access other integrations?

Sometimes a integration may want to use another integration (for example to display a grid). Should they allow each other to see and would it be possible to inject the integrations data without having the parent iFrame to see it.

[Utzel-Butzel]

Implemented the first test version, which will be included in the next release.

[Utzel-Butzel]

Here is a sample implementation: https://github.com/paperlesspaper/openintegration-xkcd