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

REST Error handling

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

REST	Detail
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.

rest-create-customer.jigx

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}'

rest-get-customers.jigx

rest-update-customer.jigx

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.

customer-errors.jigx

type: datasource.sqlite
options:
  provider: DATA_PROVIDER_LOCAL
# Configure the datasource for the customer_error table
  entities:
    - entity: customers_error
# Return the details that you specificied in the function transform property 
  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 
      [customers_error] AS error

Jigs (screens)

There are a number of options available to process items that are in an error state.

1. 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.

2. 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.

list-command-queue.jigx

title: CommandQ
description: List of commands in the queue
type: jig.list
icon: command-button-keyboard

header:
  type: component.jig-header
  options:
    height: small
    children:
      type: component.image
      options:
        source:
          uri: https://builder.jigx.com/assets/images/header.jpg
# Configure a datasource to return the data available in the system table.
datasources:
  queued-commands:
    type: datasource.sqlite
    options:
      provider: DATA_PROVIDER_LOCAL
      entities:
        - _commandQueue
      query: |
        SELECT
          id, queue, type, payload, state, error
        FROM [_commandQueue]
        ORDER BY id;
      jsonProperties:
        - payload
# Create a list of the items on the queue.
data: [email protected]

item:
  type: component.list-item
  options:
    title: =(@ctx.current.item.payload.functionId = 'rest-create-customer' ? 'Create Customer Failed':@ctx.current.item.id & " - " & @ctx.current.item.queue & " - " & @ctx.current.item.type & " - " & @ctx.current.item.state)
    subtitle: [email protected] & ' could not be created'
    description: [email protected]
    # Configure an onPress to view all the details of the individual item
    # in a separate jig.    
    onPress:
      type: action.go-to
      options:
        linkTo: item
        inputs:
          commandId: [email protected]
          internalRef: [email protected]
    # Add two actions for the items, a retry and a delete.          
    swipeable:
      left:
        - icon: close
          label: Delete
          color: negative
          onPress:
            type: action.delete-queue-command
            options:
              id: [email protected]
        - icon: button-refresh-arrow
          label: Retry
          onPress:
            type: action.retry-queue-command
            options:
              id: [email protected]

view-command-queue.jigx

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.

list-customer-errors.jigx

title: Issues
description: A list of customer records that failed to be created successfully and need manual intervention for resolution.
type: jig.list
icon: on-error-1
# Show the number of issues in the list, in a badge on the home widget.  
badge: =$count(@ctx.datasources.customer-errors)

header:
  type: component.jig-header
  options:
    height: small
    children:
      type: component.image
      options:
        source:
          uri: https://www.dropbox.com/scl/fi/vurcs49k07rna87zuhdsc/customer_issues.png?rlkey=b23lhiqprqie55v2x99u2otyy&st=upbpp2hk&raw=1

datasources:
  customer-errors:
    type: datasource.sqlite
    options:
      provider: DATA_PROVIDER_LOCAL 
      entities:
        - entity: customers_error
      query: 
        SELECT 
          id,
          json_extract(err.data, '$.response.ok') as ok, 
          json_extract(err.data, '$.screen') as screen,
          json_extract(err.data, '$.type') as type,
          json_extract(err.data, '$.entity') as entity,
          json_extract(err.data, '$.response') as response,
          json_extract(err.data, '$.request') as request,
          json_extract(err.data, '$.solution') as solution,
          json_extract(err.data, '$.user') as user,
          json_extract(err.data, '$.request.body') as body
        FROM
          [customers_error] AS err
        ORDER BY id
        
      jsonProperties: 
        - body
        - response
    
data: [email protected]
item:
  type: component.list-item
  options:
    title: =('Creating "' & @ctx.current.item.body.companyName & '" failed')
    subtitle: =(@ctx.current.item.response.status = 401 ? 'You dont have the required permission':@ctx.current.item.response.status = 403 ? 'The system was offline, try again':'')
    description: =('Error:' & ' ' & @ctx.current.item.response.statusText & ' - ' & @ctx.current.item.response.status)
    onPress: 
      type: action.go-to
      options:
        linkTo: =(@ctx.current.item.response.status = 401 ? 'customer-error-401':@ctx.current.item.response.status = 403 ? 'customer-error-403':'customer-error-500')
        inputs:
          commandId: [email protected]
    leftElement: 
      element: icon
      icon: =(@ctx.current.item.response.status = 401 ? 'lock-1':@ctx.current.item.response.status = 403 ? 'server-error-403-hand-forbidden':'on-error-1')
    rightElement: 
      element: icon
      icon: arrow-right

widgets:
  errorStatus: 
    type: widget.status
    options:
      statuses:
        - when: true
          icon: on-error-1

customer-error-401.jigx

customer-error-403.jigx

customer-error-500.jigx

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.

index.jigx

name: hello-rest-example
title: Hello REST Solution
category: sales
# onFocus is triggered when the home hub loads. 
# The sync-entities action in the global action (load-data)
# calls the Jigx REST function,
# and populates the local SQLite tables on the device
# with the data returned from REST service.
onFocus: 
  type: action.execute-action
  options:
    action: load-data
    
tabs:
  home:
    # Jig listing customers.
    jigId: list-customers
    icon: home-apps-logo
  errors:   
    # Jig listing errors from the customers_error table.  
    jigId: customer-errors
    icon: on-error-1
  list:
    # Jig listing items on the commandQueue that need to be processed. 
    jigId: list
    icon: list