configuration.md

Integration Config

A Ferdium recipe is a node module. In order to learn more about node modules and their configuration check the official Node.js documentation / npm package.json documentation.

Table of Contents

• Integration Config
  • Table of Contents
  • Config flags
  • Example

Config flags

string id mandatory
Unique identifier name of the plugin. The name of the plugin folder has to be the same.

This ID cannot contain any special characters or spaces.

string name mandatory
Display name of the service.

string version mandatory
Version number. Will be used for auto updating the integrations. The version number must be in a semver compatible format: eg 1.0.0. important: the version will be used to figure out if a new recipe update should be deployed to the user. If you make changes to a recipe, always increase the version number or Ferdium won't update your recipe.

string license
The license of the integration. We prefer MIT, but here is a list of all the available SPDX licenses http://spdx.org/licenses/

string repository
Link to your Github, Gitlab or Bitbucket public repository. Not used in the application, but is very helpful if we need to log bugs or update to newer versions, etc.

array[string] aliases
The list of alternate names that this recipe can be called

object config mandatory
This is the Ferdium-specific integration config.

• string serviceURL
  Defines the URL that should be loaded into the Ferdium webview.
  
  If you want to load a simple URL like https://www.messenger.com, you can simply define it via the serviceURL parameter. If your service URL is team based, e.g. Slack or HipChat you can use https://{teamId}.slack.com.
  
  If your service works with custom URLs, just leave this empty.
  
  Examples

{
    "serviceURL": "https://www.messenger.com"
}

{
    "serviceURL": "https://{teamId}.slack.com"
}

• boolean hasTeamId default: false
  Is this a team based service? If true, the interface to add the service will require a team identifier. e.g. [teamId].slack.com
• string urlInputPrefix
  This option is only used in combination with hasTeamId: true in order to display the value of urlInputPrefix before the input for TeamId to make it obvious to the user what input is required from them. Eg. <TeamID>.hipchat.com
• string urlInputSuffix
  This option is only used in combination with hasTeamId: true in order to display the value of urlInputSuffix after the input for TeamId to make it obvious to the user what input is required from them. Eg. <TeamID>.hipchat.com
• boolean hasHostedOption default: false
  If a service can be hosted and has a teamId or customUrl
• boolean hasCustomUrl default: false
  On-premise services like HipChat, Mattermost, ... require a custom URL. This option enables the user to enter a custom URL when adding the service.
• boolean hasNotificationSound default: false
  Some services provide their own notification sound. In order to avoid multiple sounds when the user receives a message set this to true. If the service has no built in notification sound set this to false.
• boolean hasDirectMessages default: true
  Some services have direct 1x1 messages e.g. a mention or message to every user in a channel (@channel). If this flag is set to true, the user can enable/disable if there should be a badge for direct messages.
• boolean hasIndirectMessages default: false
  Services like Slack or HipChat have direct messages e.g. a mention or message to every user in a channel (@channel) and indirect messages e.g. general discussion in a channel. If this flag is set to true, the user can enable/disable if there should be a badge for indirect messages.
• string message
  Info message that will be displayed in the add/edit service preferences screen.
• boolean disablewebsecurity default: false
  Some services like hangoutschat need the web security disabled.
• boolean allowFavoritesDelineationInUnreadCount default: false
  Services like Outlook differentiate between favorites vs other folders. Setting this to true will allow the exclusion of the message counts from those non-favorite folders.

Example

The mattermost configuration is a typical example.