-
Notifications
You must be signed in to change notification settings - Fork 0
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Documentation for customizing snap-in configuration page #63
Changes from 2 commits
d9ed601
2fe2c41
bfeb8c9
b29924a
4b95597
6a78385
5112a85
7a9500c
bb0c1f6
0ba0897
8063665
f2982dc
293238b
da64d4a
f01524a
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,106 @@ | ||
## Snap-in configuration | ||
|
||
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. | ||
|
||
## How to define a snap-in configuration page | ||
In your manifest, add the following section to enable a configuration_handler: | ||
|
||
```yaml | ||
snap_kit_actions: | ||
- name: org_snap_kit_action | ||
function: org_snap_in_configuration_handler | ||
- name: user_snap_kit_action | ||
function: user_snap_in_configuration_handler | ||
|
||
functions: | ||
- name: org_snap_in_configuration_handler | ||
description: Handler for processing organization configuration options. | ||
- name: user_snap_in_configuration_handler | ||
description: Handler for processing user configuration options. | ||
- name: config_initializer | ||
description: Generates the initial configuration options for both organization and user. | ||
|
||
configuration_handler: | ||
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. | ||
|
||
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. | ||
|
||
The functions should always return a valid snap-kit JSON such as below: | ||
```json | ||
{ | ||
"snap_kit_body": { | ||
"body": { | ||
"snaps": [ | ||
{ | ||
"elements": [ | ||
{ | ||
"action_id": "user_snap_kit_action", | ||
"action_type": "remote", | ||
"elements": [ | ||
{ | ||
"element": { | ||
"action_id": "select", | ||
"action_type": "client", | ||
"initial_selected_option": { | ||
"text": { | ||
"text": "Ticket", | ||
"type": "plain_text" | ||
}, | ||
"value": "ticket" | ||
}, | ||
"options": [ | ||
{ | ||
"text": { | ||
"text": "Ticket", | ||
"type": "plain_text" | ||
}, | ||
"value": "ticket" | ||
}, | ||
{ | ||
"text": { | ||
"text": "Conversation", | ||
"type": "plain_text" | ||
}, | ||
"value": "conversation" | ||
} | ||
], | ||
"type": "static_select" | ||
}, | ||
"type": "input_layout" | ||
} | ||
], | ||
"submit_action": { | ||
"action_id": "next", | ||
"style": "primary", | ||
"text": { | ||
"text": "Next", | ||
"type": "plain_text" | ||
}, | ||
"type": "button", | ||
"value": "next" | ||
}, | ||
"type": "form" | ||
} | ||
], | ||
"type": "card" | ||
} | ||
] | ||
} | ||
} | ||
} | ||
``` | ||
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. | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Are there any external developers which are waiting for the event-retry documentation to become public? My suggestion would be to keep this particular documentation internal and let our main snap-ins like Email, Slack etc. onboard to this mechanism first to confirm that everything works and is stable in PROD. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. yeah, removed retries doc for now since we are also revamping the backend approach. |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,68 @@ | ||
# Event Reliability in DevRev Snap-ins | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. fixed. |
||
|
||
DevRev Snap-ins platform now offers enhanced event reliability features to ensure smooth and resilient event processing. This document provides an overview of these features and how developers can leverage them to build reliable Snap-ins. | ||
codeon marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
## Retryable Errors | ||
|
||
Snap-ins can now define retryable errors using the `FunctionExecutionError` interface provided by the DevRev SDK. This allows the platform to automatically retry events that encounter intermittent or transient errors, improving overall reliability. | ||
|
||
## Retry Configuration | ||
|
||
Developers can configure the retry behavior of their Snap-in functions using the Snap-in manifest. The following options are available: | ||
|
||
```yaml | ||
functions: | ||
- name: function_name | ||
config: | ||
runtime: | ||
max_retries: 5 # number of retries before failing the event | ||
min_interval: 10 # interval in minutes between each retry | ||
codeon marked this conversation as resolved.
Show resolved
Hide resolved
|
||
``` | ||
|
||
- `max_retries`: Specifies the maximum number of retries before marking the event as failed. | ||
codeon marked this conversation as resolved.
Show resolved
Hide resolved
|
||
- `min_interval`: Specifies the minimum interval in minutes between each retry attempt. This interval may be adjusted based on the timeout of the corresponding function. | ||
codeon marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
## Error Handling | ||
|
||
The DevRev Snap-ins platform handles errors based on the ordering guarantees of the Snap-in function: | ||
codeon marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
For Snap-in functions with relaxed ordering, non-retryable errors will be marked as failed, and the error will be propagated to the DevRev platform for tracking. Retryable errors will be automatically retried based on the specified retry configuration. If the maximum number of retries is exhausted, the event will be moved to a dead-letter queue (DLQ) for further handling. | ||
codeon marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
|
||
## Error Interface | ||
|
||
The DevRev SDK introduces the `FunctionExecutionError` type to represent errors returned from the Snap-in function's run function. Developers can use this type to provide additional error details and indicate whether an error is retryable. | ||
codeon marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
```typescript | ||
class FunctionExecutionError extends Error { | ||
/** | ||
* Toggle to determine if the event should be retried or not. If not set or set to false, | ||
* the event will not be retried. | ||
*/ | ||
retry: boolean; | ||
|
||
/** | ||
* Whether to retry the event payload with updated metadata | ||
* that platform provides. Useful when the event payload is | ||
* not in a state to be directly processed, and may need new | ||
* keyrings/service account tokens or new inputs. | ||
*/ | ||
refresh?: boolean; | ||
|
||
constructor(message: string, retry: boolean, refresh?: boolean) { | ||
super(message); | ||
this.retry = retry; | ||
this.refresh = refresh; | ||
} | ||
} | ||
``` | ||
|
||
## Getting Started | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Move to near the beginning of the article. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. moved. |
||
|
||
To start using the event reliability features in your Snap-ins, follow these steps: | ||
|
||
1. Update your DevRev SDK to the latest version. | ||
2. Define retryable errors using the `FunctionExecutionError` interface in your Snap-in code. | ||
3. Configure the retry behavior in your Snap-in manifest. | ||
4. Handle errors appropriately based on the ordering guarantees of your Snap-in function. | ||
codeon marked this conversation as resolved.
Show resolved
Hide resolved
|
||
{/*5. Use the provided APIs to manage and retry failed events as needed.*/} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Having separate functions for each of these is a bit expensive. Let's combine these into a single function in our example.