rewrite

Author: codeon

fern/docs/pages/references/snap-in-configuration.mdx

@@ -1,13 +1,18 @@
-## Snap-in configuration
+# Customizing Snap-in Configuration Pages
 
-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. 
-In some instances, the default rendering page is not easy to use or doesn't faciliate the user's needs. 
-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. 
-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.
-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.
+DevRev Snap-ins platform allows developers to define custom configuration pages for their Snap-ins. This feature provides flexibility in designing user-friendly and intuitive configuration experiences tailored to the specific needs of the Snap-in.
 
-## How to define a snap-in configuration page
-In your manifest, add the following section to enable a configuration_handler:
+## Why Customize Configuration Pages?
+
+While the default configuration page automatically renders input fields for keyrings and inputs, there may be cases where a custom configuration page is more suitable:
+
+- Improved User Experience: Developers can design the configuration page to provide a more intuitive and streamlined experience for users setting up the Snap-in.
+- Advanced Input Handling: Custom configuration pages enable developers to handle complex input scenarios, such as fetching data from external systems to populate dropdown options or validating user input.
+- Branding and Styling: Developers can align the configuration page with their Snap-in's branding and style guidelines, ensuring a consistent look and feel.
+
+## Defining Custom Configuration Pages
+
+To create a custom configuration page for a Snap-in, developers need to define the following in the Snap-in manifest:
 
 ```yaml
 snap_kit_actions:
@@ -25,20 +30,24 @@ functions:
     description: Generates the initial configuration options for both organization and user.
 
 configuration_handler:
- organization:
+  organization:
     initializer: config_initializer
     snap_kit_action_name: org_snap_kit_action
-
   user:
     initializer: config_initializer
     snap_kit_action_name: user_snap_kit_action
 ```
 
-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.
+The `configuration_handler` section in the manifest connects the functions responsible for generating and processing the custom configuration page.
 
-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_kit_action` or `user_snap_kit_action` snap-kit action to process and update the snap-kit for the organization or user respectively.
+- `config_initializer`: This function generates the initial configuration options for both organization and user. It is called when the configuration page is first loaded.
+- `org_snap_in_configuration_handler`: This function processes the organization configuration options. It is triggered when actions are performed on the organization configuration snap-kit.
+- `user_snap_in_configuration_handler`: This function processes the user configuration options. It is triggered when actions are performed on the user configuration snap-kit.
+
+## Configuration Functions
+
+The configuration functions should return a valid snap-kit JSON that defines the layout and elements of the custom configuration page. Here's an example of a snap-kit JSON:
 
-The functions should always return a valid snap-kit JSON such as below:
 ```json
 {
   "snap_kit_body": {
@@ -102,5 +111,11 @@ The functions should always return a valid snap-kit JSON such as below:
   }
 }
 ```
-This will render a snap-kit with a dropdown to select between "Ticket" and "Conversation" and a "Next" button. The snap-kit will then call the `user_snap_in_configuration_handler` function when the "Next" button is clicked.
 
+In this example, the snap-kit renders a dropdown select for choosing between "Ticket" and "Conversation," along with a "Next" button. When the "Next" button is clicked, the `user_snap_in_configuration_handler` function is invoked to process the user's selection.
+
+## Conclusion
+
+Customizing Snap-in configuration pages empowers developers to create tailored and user-friendly setup experiences. By defining the layout and elements of the configuration page using snap-kit JSON, developers can guide users through the configuration process, handle complex input scenarios, and ensure a seamless integration with their Snap-in's functionality.
+
+For more details on the snap-kit JSON format and available elements, refer to the DevRev Snap-kit documentation.