Customizing snap-in configuration

The DevRev snap-ins platform allows developers to define custom configuration pages for their snap-ins.

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:

1snap_kit_actions:
2  - name: org_snap_kit_action
3    function: snap_in_configuration_handler
4  - name: user_snap_kit_action
5    function: snap_in_configuration_handler
6
7functions:
8  - name: snap_in_configuration_handler
9    description: Handler for processing organization and user configuration options.
10  - name: config_initializer
11    description: Generates the initial configuration options for both organization and user.
12
13configuration_handler:
14  organization:
15    initializer: config_initializer
16    snap_kit_action_name: org_snap_kit_action
17  user:
18    initializer: config_initializer
19    snap_kit_action_name: user_snap_kit_action

The configuration_handler section in the manifest connects the functions responsible for generating and processing the custom configuration page.

  • config_initializer: Generates the initial configuration options for both organization and user. It is called when the configuration page is first loaded.
  • snap_in_configuration_handler: This function processes the user and organization configuration options. It is triggered when actions are performed on the organization or 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:

1{
2  "snap_kit_body": {
3    "body": {
4      "snaps": [
5        {
6          "elements": [
7            {
8              "action_id": "user_snap_kit_action",
9              "action_type": "remote",
10              "elements": [
11                {
12                  "element": {
13                    "action_id": "select",
14                    "action_type": "client",
15                    "initial_selected_option": {
16                      "text": {
17                        "text": "Ticket",
18                        "type": "plain_text"
19                      },
20                      "value": "ticket"
21                    },
22                    "options": [
23                      {
24                        "text": {
25                          "text": "Ticket",
26                          "type": "plain_text"
27                        },
28                        "value": "ticket"
29                      },
30                      {
31                        "text": {
32                          "text": "Conversation",
33                          "type": "plain_text"
34                        },
35                        "value": "conversation"
36                      }
37                    ],
38                    "type": "static_select"
39                  },
40                  "type": "input_layout"
41                }
42              ],
43              "submit_action": {
44                "action_id": "next",
45                "style": "primary",
46                "text": {
47                  "text": "Next",
48                  "type": "plain_text"
49                },
50                "type": "button",
51                "value": "next"
52              },
53              "type": "form"
54            }
55          ],
56          "type": "card"
57        }
58      ]
59    }
60  }
61}

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. In the snap-kit action handler, the event.payload.action.id can be used to determine the form being submitted and call the snap-ins.update API to update the configuration.

Update snap-in inputs (beta)

Updates the inputs of a snap-in based on the inputs defined in the snap-in configuration.

Note: This endpoint is currently in beta and may be subject to change in the future. Reach out to us via PLuG to subscribe to changes to beta endpoints.

Request payload

The request payload should be a JSON object with the following properties:

  • id (string, required): The ID of the snap-in to update.
  • inputs_values (object, required): An object containing the input values to update. The properties of this object should match the input names defined in the snap-in configuration.

Example payload:

1{
2  "id": "snap_in_id",
3  "inputs_values": {
4    "part_picker": "don:core:dvrv-us-1:devo/XXXX/product:XXXX",
5    "enum_list_picker": ["value-1", "value-2"]
6  }
7}

In the example above, the part_picker and enum_list_picker are the input names defined in the snap-in configuration, and their corresponding values are provided in the inputs_values object.

Response

Success response

  • Status Code: 200 OK
  • Content-Type: application/json

Response body:

1{
2  "data": {},
3  "message": "Snap-in updated successfully",
4  "success": true
5}

Error response

If an error occurs while updating the snap-in, the response has the following format:

  • Status Code: 4xx or 5xx
  • Content-Type: application/json

Response body:

1{
2  "data": {},
3  "success": false
4}

Example usage

Here’s an example of how to update the input values:

1async updateSnapInInputs(snapInId: string, inputsValues: Record<string, any>): Promise<HTTPResponse> {
2  const payload: SnapInsUpdateRequest = {
3    id: snapInId,
4    inputsValues,
5  };
6  return this.updateSnapInInputs(payload);
7}
8
9async updateSnapInInputs(payload: SnapInsUpdateRequest): Promise<HTTPResponse> {
10  try {
11    
12    await devrevSDK.snapInsUpdate(payload);
13    return { data: {}, message: 'Snap-in updated successfully', success: true };
14  } catch (error: any) {
15    if (error.response) {
16      const err = `Failed to update the snap-in. Err: ${JSON.stringify(error.response.data)}, Status: ${error.response.status}`;
17      return { ...defaultResponse, message: err };
18    } else {
19      return { ...defaultResponse, message: error.message };
20    }
21  }
22}

In this example, the updateSnapInInputs function takes the snapInId and inputsValues as parameters. The inputsValues object should contain the input names and their corresponding values as defined in the snap-in configuration.

The function constructs the payload object with the snapInId and inputsValues, and then calls the updateSnapInInputs function to make the POST request to the snap-ins.update endpoint.

If the request is successful, it returns a success response with a status code of 200 and a message indicating that the snap-in was updated successfully.

If an error occurs, it catches the error and returns an error response with an appropriate status code and an error message containing the error details.

Note: This endpoint is currently in beta, and its functionality or parameters may change in future updates.

For more details on the snap-kit JSON format and available elements, refer to the DevRev Snap-kit documentation.