REST errors
Scenario
When trying to view a customer and their details or create a new customer in the app, the app can fail to retrieve or create the required data, and various errors are returned. In this example, we add error handling to the REST endpoint function to cater for the following errors:
401 Unauthorized
403 Forbidden
Unexpected error
How does this work
An error section is added to the REST endpoint functions for creating customers (POST), viewing customers (GET), and updating customers (PUT). In this section, the when property is configured with an expression that returns the response status from the endpoint, for example, [email protected] = 403. There are multiple when properties configured to catch a 401 and 403 error; all other response statuses are caught in the Unexpected error. Each when property has a title, icon, and description, which provides a user-friendly explanation of the error. Errors are written to the customers_error table, and the data written to the table is configured in the transform property. The table, in conjunction with the commandQueue is used to troubleshoot the error and create jigs that allows you to retry the REST call or delete the error from the commandQueue. See REST error handling for more information.
REST API
URL
https://[your_rest_service]/api/customers
Operation/Method
POST,GET,PUT
Function
In each of the REST function files (GET, POST, PUT), add an error section and configure the YAML to cater for a 401 and 403 error, and a section to cater for all other response errors.
provider: DATA_PROVIDER_REST
# Create new record in the backend
method: POST
# Use your REST service URL
url: https://[your_rest_service]/api/customers
# Direct the function call to use local execution,
# between the mobile device and the REST service.
useLocalCall: true
parameters:
x-functions-key:
location: header
required: false
type: string
# Use manage.jigx.com to define credentials for your solution.
value: service.oauth
firstName:
type: string
location: body
required: true
lastName:
type: string
location: body
required: true
companyName:
type: string
location: body
required: true
address:
type: string
location: body
required: false
city:
type: string
location: body
required: false
state:
type: string
location: body
required: false
zip:
type: string
location: body
required: false
phone1:
type: string
location: body
required: false
phone2:
type: string
location: body
required: false
email:
type: string
location: body
required: false
web:
type: string
location: body
required: false
region:
type: string
location: body
required: false
customerType:
type: string
location: body
required: false
jobTitle:
type: string
location: body
required: false
inputTransform: |
{
"firstName": firstName,
"lastName": lastName,
"companyName": companyName,
"address": address,
"city": city,
"state": state,
"zip": zip,
"phone1": phone1,
"phone2": phone2,
"email": email,
"web": web,
"region": region,
"customerType": customerType,
"jobTitle": jobTitle
}
outputTransform: |
{
"id": custId,
"status": status
}
# Configure multiple REST error responses.
error:
# Configure the specific REST endpoint error that is returned.
- when: [email protected] = 401
# Choose an icon to show in the error message.
icon: on-error-sad
# Provide a short meaningful title for the error.
title: Oops! Something Went Wrong
# Describe a user-friendly explanation for the error.
description: "It seems like you don’t have permission to Add customers.
If you think this is a mistake, please contact support. We’re here to help!"
details: =('Error:' & ' ' & @ctx.response.statusText & ' (' &
@ctx.response.status & ')')
# Write the error to the customer_error table
table: [email protected] & "_error"
# Send a notification to the app user using the title, description,
#detail and icon properties.
notification: true
# Specifiy what data must be written in the error table.
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}'
# Add the number of retries and the time between each retry.
retry:
delay: "=(@ctx.response.headers.'retry-after' ? $number(@ctx.response.headers.'retry-after') : 5) * 1000"
maxRetries: 3
# Configure the next error that could be returned from the REST endpoint.
- when: [email protected] = 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!
details: [email protected]
icon: server-error-403-hand-forbidden
notification: true
table: [email protected] & "_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}'
# All other returned REST endpoint errors will be caught
# under the Unexpected error section.
- title: Unexpected error
description:
An unexpected error occurred. Support has been notified and will
reach out via email once the issue is resolved.
details: [email protected]
# Set an automatic retry, specify the delay befre the retry is actioned,
# Set the number of retries allowed.
retry:
delay: "=(@ctx.response.headers.'retry-after' ? $number(@ctx.response.headers.'retry-after') : 5)*1000"
maxRetries: 3
icon:
table: [email protected] & "_error"
notification: true
transform:
'={ "id": @ctx.commandId, "type": "nexpected error",
"screen": "customer-error-500", "response": @ctx.response,
"request": @ctx.request, "user": @ctx.user, "solution": @ctx.solution,
"entity": @ctx.entity, "correlationId": @ctx.correlationId}'Datasources
Add a file under the datasource folder to configure the local data provider with the data returned from the customers_error table. This data is used to provide detail of the error in a jig and to configure actions allowing the item to be retried or deleted.
Jigs (screens)
There are a number of options available to process items that are in an error state.
Use the commandQueue. Items that return an error from the REST endpoint will remain on the commandQueue and are not automatically processed by the queue. You must configure an action to either retry the item or delete the item from the queue. The retry executes the REST call again.
Use the customer_error table configured in the function. Use the data from the table in a jig to allow app users to resolve the error or delete the item in error.
Use the commandQueue
Create two jigs to work with the items in the commandQueue. This is helpful for the solution owner or administrator to take action and delete errors in the queue or possibly retry the REST call to process the items in the queue that are in an error state. Configure a list jig containing all items in the commandQueue, add a left swipeable action to cater for the delete and retry actions, also add an onPress event to go to view the payload details of the item in error.
Use the customers_error table
Create a list jig to list the records in the customers_error table. Provide detail of the error in the title and subtitle properties.
Index
For performance and offline support the data is synced from the REST service as soon as the app is opened or receives focus. This is achieved by calling the global action in the onFocus events. The action.sync-entities action will delete any items from the local data provider that were deleted from the commandQueue.
Last updated
Was this helpful?