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 functions to cater for the following errors:

• 401 Unauthorized
• 403 Forbidden
• Unexpected error

Error REST 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, =@ctx.response.status = 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:

• An alert notification message configured which is displayed either as a toast or modal to the user in the app.
• An operation which writes the details to the customers_error table for logging and debugging purposes, which provides an explanation of the error. The data written to the table is configured in the records 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.

Consideration

• Use groupId to manage multiple alerts for the same issue. When using modal presentation, alerts with the same groupId are grouped so that only the first alert appears and subsequent ones are automatically skipped. When using toast presentation, alerts are also grouped, preventing duplicates. Users can tap the toast to view details, if multiple alerts exist, they stack and display a count at the top. Swiping left lets users view each alert’s details within the stack.
• When configuring error handling with alerts, ensure that HTTP 200 (success) responses are excluded. If not, the app may treat successful responses as errors, preventing data from loading.

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 with alerts 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:
  # Error handling with Alert 401.
  - when: =@ctx.response.status = 401
    # Enable notification to alert the user.
    notification: true
    # Configure the alert modal that appears to the user.
    alert:
      # Main heading displayed to the user.
      title: Insufficient Permissions
      # Detailed user-friendly explanation of the error and next steps.
      description: You don’t have permission to Add customers.
        Please contact support to assign you the correct permissions.
      # Dynamic subtitle showing the actual HTTP status text and code.
      subtitle: =('Error:' & ' ' & @ctx.response.statusText & ' (' &
        @ctx.response.status & ')')
      # Icon to visually represent the error state.
      icon: lock-2
      style:
        isNegative: true
      presentAs: modal
    # Operations to execute when this error occurs.
    operations:
      # Log the error to a database table for tracking and debugging.
      - type: operation.upsert-merge
        # Dynamic table name based on the entity (e.g., "customers_error").
        table: =@ctx.entity & "_error"
        # Error record containing all relevant context information.
        records: '={ "id": @ctx.commandId, "type": "Unauthorized",
          "response": @ctx.response, "request": @ctx.request, "user": @ctx.user,
          "solution": @ctx.solution.name, "entity": @ctx.entity, "correlationId": @ctx.correlationId}'
        # Timestamp when the error was logged.
        timestamp: =$now()

  # Error handling with Alert 403
  - when: =@ctx.response.status = 403
    notification: true
    alert:
      title: System Offline
      description: Our system is temporarily unavailable.
        Please try again in a few minutes. Thank you
        for your patience!
      subtitle: =@ctx.response.body
      icon: server-error-403-hand-forbidden
      style:
        isWarning: true
      presentAs: modal
      # Modal can be dismissed.
      dismiss:
        isEnabled: true
      # Configure an action to retry the POST or cancel and go back to the form.
      actions:
        - type: action.retry-queue-command
          options:
            id: =@ctx.commandId
            title: Retry Now
            style:
              isPrimary: true
        - type: action.go-to
          options:
            title: Cancel
            linkTo: new-customer-hr1
    # Log the error to a database table for tracking and debugging.
    operations:
      - type: operation.upsert-merge
        table: =@ctx.entity & "_error"
        records: '={ "id": @ctx.commandId, "type": "system-offline",
          "response": @ctx.response, "request": @ctx.request, "user": @ctx.user,
          "solution": @ctx.solution.name, "entity": @ctx.entity, "correlationId": @ctx.correlationId}'
        timestamp: =$now()
    # Error handling with Alert for all non-success responses.
    # Exclude the 200 (successful) response; otherwise, no data will load in the app.
    # A 200 status is considered a valid response and should not trigger an error alert.
    # Without this exclusion, it would be treated as an error, preventing data from loading.
  - when: =@ctx.response.status != 403 or @ctx.response.status != 401 or @ctx.response.status != 200
    notification: true
    alert:
      title: Unexpected error
      description: An unexpected error occurred. Please try again.
      subtitle: =@ctx.response.body
      icon: on-error-1
      presentAs: toast
      group:
        id: unexpectedErrors
      # Configure an action to retry the POST or cancel and go back to the form.
      actions:
        - type: action.retry-queue-command
          options:
            id: =@ctx.commandId
            title: Retry again
            style:
              isPrimary: true
        - type: action.go-to
          options:
            title: Cancel
            linkTo: new-customer-hr1
    # Log the error to a database table for tracking and debugging.
    operations:
      - type: operation.upsert-merge
        table: =@ctx.entity & "_error"
        records: '={ "id": @ctx.commandId, "type": "unexpected-error",
          "response": @ctx.response, "request": @ctx.request, "user": @ctx.user,
          "solution": @ctx.solution.name, "entity": @ctx.entity, "correlationId": @ctx.correlationId}'

rest-get-customers.jigx

rest-update-customer.jigx

rest-upload-customer-images.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 specified in the function transform property 
  query: 
    SELECT 
      id,
      json_extract(data, '$.response.ok') as ok, 
      json_extract(data, '$.response.status') as status, 
      json_extract(data, '$.response.statusText') as statusText, 
      json_extract(data, '$.response.headers') as headers, 
      json_extract(data, '$.response.body') as body,
      json_extract(data, '$.type') as type
    FROM 
      [customers_error]

Error Center - 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 customers_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.
3. Add a banner component to the home screen with a when condition that displays when errors exist in the customers_error table. Add an action to go-to the issues (error center) list.

Error Center

Add a banner to the customer list

Add a banner component with a when condition that displays when errors exist in the customers_error table. Use an expression with $count in the banner title to show the number of errors. Include a go-to action that navigates to the list of issues and errors. Configure the list to display the error type, statusText, and status.

Enable Retry and Delete swipe actions. When deleting an error, ensure the delete action removes the record from both the commandQueue and the customers_error table.

home.jigx

title: Global Inc
type: jig.default

children:
  # Error Banner - only shows when errors exist in the queue
  - type: component.banner
    # Use 'when' to conditionally display banner only when errors exist
    when: =$count(@ctx.datasources.customers-errors) != 0
    options:
      title:
        # Expression to show the number of current errors.
        text: ="Errors " & ($count(@ctx.datasources.customers-errors.id))
        fontSize: medium
        isBold: true
        color: negative
      subtitle:
        text: Errors detected, review and resolve issues.
        fontSize: regular
      leftElement:
        element: icon
        icon: on-error-1
        type: contained
        shape: circle
        color: negative
      style:
        isNegative: true
      actions:
        - type: action.action-list
          options:
            title: See All
            actions:
              - type: action.go-to
                options:
                  linkTo: customer-errors
  - type: component.grid
    options:
      children:
        - type: component.grid-item
          options:
            size: "2x2"
            children:
              type: component.jig-widget
              options:
                jigId: list-customers-hr1
        - type: component.grid-item
          options:
            size: "2x2"
            children:
              type: component.jig-widget
              options:
                jigId: list-customers-hr2
        - type: component.grid-item
          options:
            size: "2x2"
            children:
              type: component.jig-widget
              options:
                jigId: list-customers-hr3

Use the commandQueue

Create a jig 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.

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: =@ctx.datasources.queued-commands
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: =@ctx.current.item.payload.data.companyName & ' could not be created'
    description: =@ctx.current.item.payload.data.internalRef
    # 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: =@.current.item.id
          internalRef: =@ctx.current.item.payload.data.internalRef
    # 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: =@.current.item.id
        - icon: button-refresh-arrow
          label: Retry
          onPress:
            type: action.retry-queue-command
            options:
              id: =@.current.item.id

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.
• Add a swipeable event and configure a retry-queue-command action, and two execute-entity actions to delete the records from the commandQueue and the customers_error tables.
• Similarly, add actions to the list that retry or delete all errors in the list. The execute-entities action is used with specific expressions that include multiple records:

  • =@ctx.datasources.command-queue.id - retries multiple items in the CommandQueue at the same time.
  • =@ctx.datasources.customers-errors.{"id":id}[] - deletes all records in the customers_error table.

customer-errors.jigx

title: Issues
description: A list of errors that failed to be created successfully and need manual intervention for resolution.
type: jig.list
icon: on-error-1

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

data: =@ctx.datasources.customers-errors
item:
  type: component.list-item
  options:
    title: =@ctx.current.item.type
    subtitle: =@ctx.current.item.statusText & ' - ' & @ctx.current.item.status
    leftElement:
      element: icon
      icon: =(@ctx.current.item.status = 401 ? 'lock-1':@ctx.current.item.status = 403 ? 'server-error-403-hand-forbidden':'on-error-1')
      color: negative
    rightElement:
      element: icon
      icon: arrow-left-diagram
    swipeable:
      left:
        - label: Retry
          icon: synchronize-arrow
          color: primary
          onPress:
            type: action.retry-queue-command
            options:
              id: =@ctx.current.item.id
        - label: Delete
          icon: bin-2-alternate
          color: negative
          onPress:
            type: action.action-list
            options:
              isSequential: true
              actions:
                - type: action.execute-entity
                  options:
                    provider: DATA_PROVIDER_LOCAL
                    entity: _commandQueue
                    method: delete
                    data:
                      id: =@ctx.current.item.id
                - type: action.execute-entity
                  options:
                    provider: DATA_PROVIDER_LOCAL
                    method: delete
                    entity: customers_error
                    data:
                      id: =@ctx.current.item.id

actions:
  - numberOfVisibleActions: 2
    children:
      - type: action.retry-queue-command
        options:
          title: Retry all
          # Retry all items in the queue.
          id: =@ctx.datasources.command-queue.id
      - type: action.action-list
        options:
          title: Delete all
          isSequential: true
          actions:
            - type: action.delete-queue-command
              options:
                # Delete all items in the queue.
                id: =@ctx.datasources.command-queue.id
            - type: action.execute-entities
              options:
                provider: DATA_PROVIDER_LOCAL
                method: delete
                entity: customers_error
                # Delete multiple (all) records in the table.
                data: =@ctx.datasources.customers-errors.{"id":id}[]

datasource

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.

index.jigx

name: hello-rest-example
title: Hello REST Solution
category: sales
# onLoad is triggered when the app 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.
onLoad:
  type: action.action-list
  options:
    isSequential: true
    actions:
      - type: action.execute-action
        options:
          action: load-data
      - type: action.execute-action
        options:
          action: load-us-states
          
onRefresh:
  type: action.action-list
  options:
    isSequential: true
    actions:
      - type: action.execute-action
        options:
          action: load-data
      - type: action.execute-action
        options:
          action: load-us-states    
tabs:
  Home:
    jigId: home
    icon: home-apps-logo
    label: Home
  customers1:
    jigId: list-customers-hr1
    icon: number-one-square
    label: Customers
  customers2:
    jigId: list-customers-hr2
    icon: number-two-square
    label: All Customers
  customers3:
    jigId: list-customers-hr3
    icon: number-three-square
    label: Customers & Images
  errors:
    jigId: customer-errors
    icon: on-error-1
  listCommandQueue:
    jigId: list-command-queue
    icon: command-button-keyboard  

load-data.jigx

load-states.jigx

See Also

• Configuring OAuth error messages