REST error handling

rest errors returned by the endpoints in an app are often too technical for end users to comprehend jigx allows you to customize these error messages to improve user experience, communicate more effectively, and ensure users understand that errors are not their fault by configuring custom error handling, you can suppress or customize default error messages log error details for more effective debugging create more robust and user friendly error solutions key features custom error messages control the message shown to users when a rest error occurs user friendly retry options allow users to retry an action when an error occurs by default, jigx automatically catches any 429 error responses and retries the request up to three times, with a five second delay between each attempt error logging automatically log error details for debugging dynamic responses build logic to respond to specific errors flexibly standard rest errorcustomized rest error how does it work in jigx, rest error handling is configured through an error section in the rest function this allows the system to catch various error responses and act accordingly multiple error responses can be defined and are evaluated in sequence error responses can trigger notifications, log errors, or provide retry options for users the app supports customized messaging for each error type expressions are supported in functions high level steps configure the error section in the rest function to customize the error message and configure an error table create a datasource for the error table create a ui (jig) to process the error in the queue using the commandqueue actions by default, jigx automatically handles 429 (too many requests) error responses for crud and sync methods by retrying the request up to three times, with a five second delay between each attempt if the request still fails after the third retry, the error is raised in the app you can customize this behavior by configuring the handling of the 429 status in the error property rest function in the jigx function, configure the error section to cater for customizing the error message determining if a toast notification is required or not writing the context of the error to a table for debugging and configuring actions to fix the error multiple error handlers can be added in the function, which are executed from the top to bottom until one matches the error section needs to be configured in each of the individual rest function files configuration properties the following properties are available for configuration when handling rest errors property description description provide a user friendly message of the error, for example, " it looks like our system is unavailable " defaults to the provider's description if absent for example, the rest provider uses the http status code and message the description property supports localization docid\ uro2d0jmtmm9 lzwakm q details add additional information that will display under the description defaults to the provider's details if absent icon select an jigx icons docid 0vs mac9xgx524crpdiar to show on the error notification screen notification determines whether the notification should be shown on the device (true/false) retry provides the ability to configure an automatic retry, set a delay time before the retry is executed and specify the maximum number of retries allowed by default, jigx automatically handles 429 (too many requests) error responses for crud and sync methods by retrying the request up to three times, with a five second delay between each attempt if the request still fails after the third retry, the error is raised in the app you can customize this behavior by configuring the handling of the 429 status in the error property table define a table where the error information specified in the transform property will be logged to, for example table =@ctx entity & " error" title title that displays on the toast notification defaults to the provider's title if not provided the title property supports localization docid\ uro2d0jmtmm9 lzwakm q transform specifies the details to log in the table for the error, such as the request, response, and user context, for example '={ "id" @ctx commandid, "type" "system offline", "screen" "system offline", "response" @ctx response, "request" @ctx request, "user" @ctx user, "solution" @ctx solution, "entity" @ctx entity, "correlationid" @ctx correlationid}' | \| when | checks if the result of the function is an error, the first one that resolves to true is used the rest provider uses a combination of actual errors encountered and the http status code and message configure different types of actions depending on the error received, by using multiple when statements \ if the property is not configured it defaults to the rest provider's default error check | example configuration rest function # configure an error section in each function file for rest endpoint, \# where errors can occur error \ when =@ctx response status = 403 title system offline description it looks like our system is temporarily unavailable we're working hard to fix this and get things back on track please try again in a little while thank you for your patience! \# set an automatic retry, specify the delay before the retry is actioned, \# set the number of retries allowed retry delay "=(@ response headers 'retry after' ? $number(@ response headers 'retry after') 5) 1000" maxretries 3 details =@ctx response body icon server error 403 hand forbidden notification false table datasync error transform '={ "id" @ctx parameters syncid, "type" "system offline", "screen" "system offline", "response" @ctx response, "request" @ctx request, "user" @ctx user, "solution" @ctx solution, "entity" @ctx entity, "correlationid" @ctx correlationid}' error logging logging errors is a crucial part of the error handling mechanism errors are logged into a dedicated error table defined by you, capturing key information for debugging and analysis take the information that you currently have in the context of the function and log it to the table by defining the data to be logged in the transform property the full error coming back from the backend system should be logged expose error tables in jigx builder to help with troubleshooting define a datasource against the error tables error logging configuration when configuring rest errors, several system expressions and variables can be used these variables allow you to dynamically log and handle errors based on the context of the function call the following context is available to write to the error table, using =@ctx variable value variables value commandid unique id logged for the item on the commandqueue the id matches the id in the entity table correlationid the unique identifier that appears in the app it is used in troubleshooting (solution) docid 0ayeejxj3sk bgmne roy to help identify specific entries in the logs and to follow the user's journey while using the solution in the app by filtering logs using this id, you can troubleshoot issues more effectively entity the specified table where the error context is logged error message string title string description string details string icon string table string notification boolean | \| parameters | specify any of the parameters in the function to be logged to the error table | \| request | method string url string headers record\<string, string> body\ string|buffer | \| response | ok boolean status number statustext string headers record\<string, string> body any | \| solution | id solutionid name solutionname organizationid organizationid settings custom record\<string, unknown> | \| user | id string email string displayname string avatarurl string phone string isverified boolean settings record\<string, unknown> | function error table # configure the error table and the data to log to the table, \# in the error section of the function table =@ctx entity & " error" transform '={ "id" @ctx commandid, "type" "system offline", "screen" "system offline", "response" @ctx response, "request" @ctx request, "user" @ctx user, "solution" @ctx solution, "entity" @ctx entity, "correlationid" @ctx correlationid}' error datasource # call the error details from the dedicated error table in a datasource \# use the datasource to configure jigs to action the error, e g retry type datasource sqlite options provider data provider local entities \ entity datasync error query select id, json extract(err data, '$ response ok') as ok, json extract(err data, '$ response status') as status, json extract(err data, '$ response statustext') as statustext, json extract(err data, '$ response headers') as headers, json extract(err data, '$ response body') as body, json extract(err data, '$ screen') as screen, json extract(err data, '$ type') as type from \[datasync error] as err commandqueue table & actions the commandqueue is a system table, when a device is offline items are queued on the table when the device comes online the items in the queue are processed however, if items on the queue go into error, they are not processed and remain on the queue errors from rest methods, except for action sync entity/entities are queued in the commandqueue table the commandqueue is exposed in jigx dev tools, allowing you to debugging docid\ ckwtdzjxtojdm 642bgc you can expose the commandqueue table in a jig and then use the commandqueue actions to interact with the queued items that are in error state by either performing a retry or delete take note that when syncing an item or when the device is offline the commandid is not available commandqueue actions there are two actions related specifically to the commandqueue namely action retry queue command executes a retry of the rest function called action delete queue command only deletes the item from the commandqueue the record will still be saved locally on the device you need to provide separately for the deleting of the local data, which can be achieved through an action sync entity/entities or executing a delete method on the local data provider action configuration swipeable left \ icon close label delete onpress type action delete queue command options id =@ctx current item id \ icon button refresh arrow label retry onpress type action retry queue command options id =@ctx current item id considerations the commandid matches the id in the error table, this is important when you want to build a jig/ui to deal with the error when using the commandqueue actions the commandqueue id ( commandid ) is required use the error table to build a jig/ui as there is more data logged to the table than the commandqueue commandid & error id use the commandqueue table as a datasource in your solution it behaves like a normal entity table with change events and updates when uselocalcall true is set, functions that rely on secrets or other authentication mechanisms not available locally will not execute examples and code snippets see rest error example https //docs jigx com/examples/rest errors to understand how to configure error responses in a rest function, create a error table and use the commandqueue with actions to process the error