diff options
author | vantezzen <hello@vantezzen.io> | 2020-03-08 11:10:17 +0100 |
---|---|---|
committer | vantezzen <hello@vantezzen.io> | 2020-03-08 11:10:17 +0100 |
commit | 9d715597a600710c20f75412d3dcd8cdb7b3c39e (patch) | |
tree | 65ab812834d486aaccf35e2a31a7a628a7100422 /docs/configuration.md | |
parent | Revert to using the standart file comparison function (diff) | |
download | ferdium-recipes-9d715597a600710c20f75412d3dcd8cdb7b3c39e.tar.gz ferdium-recipes-9d715597a600710c20f75412d3dcd8cdb7b3c39e.tar.zst ferdium-recipes-9d715597a600710c20f75412d3dcd8cdb7b3c39e.zip |
Add documentation
Diffstat (limited to 'docs/configuration.md')
-rw-r--r-- | docs/configuration.md | 92 |
1 files changed, 92 insertions, 0 deletions
diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..923ed19 --- /dev/null +++ b/docs/configuration.md | |||
@@ -0,0 +1,92 @@ | |||
1 | # Integration Config | ||
2 | |||
3 | A [Ferdi](https://getferdi.com) recipe is a node module. In order to learn more about node modules and their configuration check the official [Node.js documentation](https://nodejs.org/api/modules.html) / [npm package.json documentation](https://docs.npmjs.com/files/package.json). | ||
4 | |||
5 | ## Table of Contents | ||
6 | * [Config flags](#user-content-config-flags) | ||
7 | * [Examples](#user-content-examples) | ||
8 | |||
9 | ## Config flags | ||
10 | |||
11 | `string` **id**<br /> | ||
12 | Unique identifier name of the plugin. The name of the plugin folder has to be the same. | ||
13 | |||
14 | This ID cannot contain any special characters or spaces. | ||
15 | |||
16 | `string` **name**<br /> | ||
17 | Display name of the service. | ||
18 | |||
19 | `string` **version**<br /> | ||
20 | Version number. Will be used for auto updating the integrations. The version number must be in a semver compatible format: `1.0.0`. | ||
21 | **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 Ferdi won't update your recipe. | ||
22 | |||
23 | `string` **description**<br /> | ||
24 | Short description about your integration. Not currently used. | ||
25 | |||
26 | `string` **main**<br /> | ||
27 | The plugins main entry point. In our case `index.js`. | ||
28 | |||
29 | `string` **author**<br /> | ||
30 | Author of the integration. Not currently used. | ||
31 | |||
32 | `string` **license**<br /> | ||
33 | The license of the integration. We prefer MIT, but here is a list of all the available SPDX licenses http://spdx.org/licenses/ | ||
34 | |||
35 | `string` **repository**<br /> | ||
36 | Link to your Github, Gitlab or Bitbucket public repository | ||
37 | |||
38 | `object` **config**<br /> | ||
39 | This is the Ferdi specific integration config. | ||
40 | |||
41 | * `string` **serviceURL**<br/> | ||
42 | Defines the URL that should be loaded into the Ferdi webview. | ||
43 | <br /><br /> | ||
44 | 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`. | ||
45 | <br /><br /> | ||
46 | If your service works with custom URLs, just leave this empty. | ||
47 | <br /><br /> | ||
48 | **Examples** | ||
49 | ```json | ||
50 | { | ||
51 | "serviceURL": "https://www.messenger.com" | ||
52 | } | ||
53 | ``` | ||
54 | <br /> | ||
55 | |||
56 | ```json | ||
57 | { | ||
58 | "serviceURL": "https://{teamId}.slack.com" | ||
59 | } | ||
60 | ``` | ||
61 | * `boolean` **hasTeamId** _default: true_<br /> | ||
62 | Is this a team based service? If true, the interface to add the service will require a team identifier. e.g. `[teamId]`.slack.com | ||
63 | * `boolean` **urlInputSuffix**<br /> | ||
64 | 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 him. Eg. _<TeamID>.hipchat.com_ | ||
65 | * `boolean` **hasCustomUrl** _default: false_<br /> | ||
66 | On premise services like HipChat, Mattermost, ... require a custom URL. This option enables the user to enter a custom URL when adding the service. | ||
67 | * `boolean` **hasNotificationSound** _default: false_<br /> | ||
68 | 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`. | ||
69 | * `boolean` **hasIndirectMessages** _default: false_<br /> | ||
70 | 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. | ||
71 | * `string` **message**<br /> | ||
72 | Info message that will be displayed in the add/edit service interface. | ||
73 | |||
74 | ## Example | ||
75 | ### Mattermost configuration | ||
76 | ```json | ||
77 | { | ||
78 | "id": "mattermost", | ||
79 | "name": "Mattermost", | ||
80 | "version": "1.0.0", | ||
81 | "description": "Mattermost", | ||
82 | "main": "index.js", | ||
83 | "author": "Stefan Malzner <stefan@adlk.io>", | ||
84 | "license": "MIT", | ||
85 | "repository": "https://github.com/meetFerdi/recipe-mattermost", | ||
86 | "config": { | ||
87 | "hasNotificationSound": true, | ||
88 | "hasIndirectMessages": true, | ||
89 | "hasCustomUrl": true | ||
90 | } | ||
91 | } | ||
92 | ``` | ||