|
| 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