Documentation for snap-in configuration page and event retries #63
Conversation
|
|
||
| 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. | ||
|
|
||
| ## Why Customize Configuration Pages? |
There was a problem hiding this comment.
Remove this heading, it's unnecessary.
Co-authored-by: Ben Colborn <[email protected]>
| 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: |
There was a problem hiding this comment.
Having separate functions for each of these is a bit expensive. Let's combine these into a single function in our example.
| "message": "Snap-in updated successfully", | ||
| "success": true | ||
| } | ||
| ``` | ||
|
|
||
| #### 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: | ||
| ```json | ||
| { | ||
| "data": {}, | ||
| "message": "Failed to update the snap-in. Err: {error details}, Status: {status code}", |
There was a problem hiding this comment.
I think the message field would be removed if we make the API beta.
|
|
||
| async updateSnapInGlobalVariable(payload: Record<string, any>): Promise<HTTPResponse> { | ||
| try { | ||
| await axios.post(`${this.endpoint}/internal/snap-ins.update`, payload, this.configs); |
There was a problem hiding this comment.
reminder to update this to use devrevSDK?
| return this.updateSnapInGlobalVariable(payload); | ||
| } | ||
|
|
||
| async updateSnapInGlobalVariable(payload: Record<string, any>): Promise<HTTPResponse> { |
There was a problem hiding this comment.
nit: globalVariable as a term is not exposed to the external developers. Let's use inputs?
|
|
||
| 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. | ||
|
|
||
| Please keep in mind that this endpoint is currently in BETA, and its functionality or parameters may change in future updates. |
There was a problem hiding this comment.
Thinking out loud - Should we have some sort of subscribe to beta changes button in our documentation which can help us keep track of who all external parties which are using a beta feature? It can help us in the future when we need to track down who all are depending on this feature.
There was a problem hiding this comment.
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.
| config: | ||
| runtime: | ||
| max_retries: 5 # number of retries before failing the event | ||
| min_interval: 10 # interval in seconds between each retry |
There was a problem hiding this comment.
nit: Let's use a more realistic value
| min_interval: 10 # interval in seconds between each retry | |
| min_interval: 120 # interval in seconds between each retry |
|
|
||
| The DevRev snap-in platform handles errors based on the ordering guarantees of the snap-in function. | ||
|
|
||
| For snap-in functions with relaxed ordering, non-retryable errors are marked as failed, and the errored event is propagated to the DevRev platform for tracking. Retryable errors are automatically retried based on the specified retry configuration. If the maximum number of retries is exhausted, the errored events are moved to a dead-letter queue (DLQ) for further handling. |
There was a problem hiding this comment.
Right now all snap-in-functions have relaxed ordering. Mentioning this here might be confusing.
| For snap-in functions with relaxed ordering, non-retryable errors are marked as failed, and the errored event is propagated to the DevRev platform for tracking. Retryable errors are automatically retried based on the specified retry configuration. If the maximum number of retries is exhausted, the errored events are moved to a dead-letter queue (DLQ) for further handling. | |
| For snap-in functions with ordering, non-retryable errors are marked as failed, and the errored event is propagated to the DevRev platform for tracking. Retryable errors are automatically retried based on the specified retry configuration. If the maximum number of retries is exhausted, the errored events are moved to a dead-letter queue (DLQ) for further handling. |
ISS-98485
ISS-100260
ISS-98417