Skip to content

Commit d9ed601

Browse files
committed
Init docs for snap-in configuration
1 parent 99fb695 commit d9ed601

File tree

1 file changed

+35
-0
lines changed

1 file changed

+35
-0
lines changed
Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
## Snap-in configuration
2+
3+
Snap-ins have keyrings and inputs that can be set from the UI by going to the snap-in configuration page. The snap-in configuration page will list all the keyrings and inputs which can then be set by the user installing the snap-in.
4+
In some instances, the default rendering page is not easy to use or doesn't faciliate the user's needs.
5+
In such cases, the snap-in configuration page can be defined by the snap-in developer. The snap-in developer can define a snap-in function that can be used to generate a snap-kit which renders input elements as well as other elements to make the page easier to configure or pull in data from other systems as well.
6+
For example, if the developers needs to ask the user for a Slack channel, they may need to get the list of channels from their Slack workspace, show the channel names in the drop down and when the user selects a channel, the snap-kit can pass back the channel ID as that is what is used in the APIs.
7+
This enables a lot of flexibility in the snap-in configuration page making it easier to configure snap-ins and giving developers more control of how users interact with their snap-ins.
8+
9+
## How to define a snap-in configuration page
10+
In your manifest, add the following section to enable a configuration_handler:
11+
12+
```yaml
13+
functions:
14+
- name: org_snap_in_configuration_handler
15+
description: Handler for processing organization configuration options.
16+
- name: user_snap_in_configuration_handler
17+
description: Handler for processing user configuration options.
18+
- name: config_initializer
19+
description: Generates the initial configuration options for both organization and user.
20+
21+
configuration_handler:
22+
organization:
23+
initializer: config_initializer
24+
snap_kit_action_name: org_snap_in_configuration_handler
25+
26+
user:
27+
initializer: config_initializer
28+
snap_kit_action_name: user_snap_in_configuration_handler
29+
```
30+
31+
The above YAML segment creates three functions and connects them to the configuration_handler to enable custom snap-kits to be rendered as the snap-in configuration page. The `config_initializer` function is used to generate the initial configuration options for both organization and user. The `org_snap_in_configuration_handler` and `user_snap_in_configuration_handler` functions are used to process the organization and user configuration options respectively.
32+
33+
When the snap-in configuration page is loaded, the snap-in will call the `config_initializer` function to get the initial configuration options. Further actions on the returned snap-kit will then call the `org_snap_in_configuration_handler` or `user_snap_in_configuration_handler` function to render the snap-kit for the organization or user respectively.
34+
35+
The functions should always return a valid snap-kit JSON.

0 commit comments

Comments
 (0)