Monitoring errors - mobile user and administrator responsibilities

To identify why errors occur on a device, it is important to understand how transactions are treated and the flow of data between the client and your data source.

The client can be used either online or offline.  Records are created or updated on a mobile device and are upsynced when a connection to the Swift MEAP server is available.  These records have to be processed in the sequence that they were created on a device in order to maintain data integrity. 

The Swift MEAP client will not submit a transaction until it receives a success or failure notification from the Swift MEAP server for the previous transaction sent.  The Swift MEAP server will not submit a transaction to your datasource for processing unless other transactions ahead of it have been processed. 

In effect, this means there are two queues, one on the client which holds records waiting to upsync to the Swift MEAP server (the device request queue).  The second is the list of records that could not be processed or are waiting to be processed (the server Delivery In Queue).  Even if a record is in the Delivery In queue, it does not necessarily mean that there is an error with that record, it could be in the queue, waiting for another (failed) record ahead of it to be processed.

Difference between updating and fixing records

If a record fails, it cannot be corrected on a device by simply editing the record and selecting another value.   So if a user enters an incorrect date in an appointment (which fails against the data source), they cannot tap the edit button on the client and change the appointment date.  In this case, they are not correcting the original transaction, they are creating a second transaction that cannot be processed until the first transaction has been fixed (which is in error).

The user has performed two distinct changes:

1. Record creation (new transaction request) with incorrect date
2. Update request with corrected date

Therefore, we class records within two categories:

1. Update: These are transactions created in sequence that must be processed in sequence.  These are created using the “Edit” icon in the application.  Editing records will not correct issues with records that previously failed, they will just queue another transaction to be processed, once the failed record has been fixed.
2. Fix:  This is a fix to the original transaction, a non-sequential event.  It can be performed by the administrator in the Delivery In queue or by users on a device. 

Critical monitoring

It is critical that both end users and administrators take responsibility for ensuring the following:

• Records are not waiting to upsync to the server in the device queue
• Failures to transactions are identified and fixed

Any records reported as failures and any records that require the failed record to be processed before they can be submitted (pending) will not exist in your data source, they have not been processed successfully.  Therefore, the only place that they exist is on a device and within the Swift MEAP server (Delivery In queue).

All failures are reported to the user on a device.  Administrators can monitor errors within the Swift MEAP console application.  Failures are not automatically fixed, they need to be acted upon.  It is often best to set up email notification in the server, so that administrators are aware of any errors as they occur. 

If issues are not fixed promptly, they can result in further complications. For example, if a record is processed at a later date, records could fail due to further time sensitive validation in place on your data source.  If, for example, your data source only allows submission of activities within 7 days of them occurring and a user submits an Activity after 6 days, if the submission fails (for any reason) and is not fixed for three or four days, administrators could find that although the original reason for failure was resolved, they are no longer able to process any update to the record.

Checking failures / queue on the client

There are two areas which should be monitored on a device:

Records waiting to upsync - client

The network indication icon is a series of green / red vertical bars in the bottom left of the tablet display.  The icon is green (indicating web access is available) or red (indicating no network access is available). 

Records waiting to upsync are indicated in an amber circle.  The number of records waiting to upsync is displayed in the circle icon.  When the client connects to the Swift MEAP server, records in the device queue should be upsynced to the server.

Details of transactions in the queue can be viewed on the phone or tablet by going to Settings->Advanced Options->Show Queue

Failures - client

Records that have failed (either due to validation in your Data Source or an inability to present the record to your data source) are displayed as a red circle on the Sync Log icon.  The number of records that have failed are listed within the red circle icon.  If no icon is present, there are no failures for the current client.

Failures can also be checked by clicking on the Sync Log icon and selecting “Failed” from the drop down selection box to view failed records.  Each failed record is listed individually, selecting a transaction will show details of the failure message returned from your data source (or from the Swift MEAP server if the data source was unavailable).

If administrators have allowed users to fix records, the “Fix record” button will be listed in the sync log, once a record has been selected.  If the “Fix record” button is not available, the record can only be fixed by your server administrator.  Editing the record to change values will not fix the original transaction.

Checking failures / queue on the server

Failed and pending records can be checked by selecting Queues->Delivery In.  Each transaction has an “Edit transaction” button, where you can view details of the transaction, related records and details of the error message received.

You can alter any values in the “Edit transaction” screen and submit them for processing against your data source.  If successfully processed, the transaction is handled as if the record were fixed on a device.  A success notification will be returned to the device and any fields that were altered by the administrator will be sent to the client, so that server and client records contain the same data.

During upsyncing of transactions from the client queue, the following occurs:

1. The server checks to see if there are any related records ahead of it in the Delivery In queue.  If there are, the current record will be marked as Pending and processed when other errors ahead of it are fixed.  When checking related records, the server checks delivery in for:
   1. Transactions with the same record id
   2. Transactions linked to the current record (through a REFERENCE field).  For example, if you create an appointment and it fails, then create child records (child of appointment) on a device, the server will recognise that the appointment record should be processed first.  It will therefore queue any children for processing later (Pending).
   3. If there are no records ahead of it in the queue, the current record is processed against your datasource, resulting in two outcomes:
      1. Success:  If the data source returns a success notification, it is returned to the server and then the device.  The next transaction in the device queue is then submitted.
      2. Failure:  The current record is inserted into Delivery In, this allows the server to continue processing the device queue.  A failure notification (with a message) is returned to the mobile user, the client logs the failure and submits the next record to the Swift MEAP server.  Any records now upsynced that are related to the failed record will be inserted into the Delivery In queue, as pending transactions.

Any records in FAILED or RETRIED status will be processed again by the QueueJob.  When the QueueJob is run, the following occurs:

1. The QueueJob will scan the delivery in table for records that fall into the current processing window.  Usually, records that failed within the last 24 hours are re-processed automatically.  Once the record is over 24 hours old, it has been submitted several times and the failure is considered permanent, therefore it will no longer be processed by the QueueJob.
2. The QueueJob will ignore any Pending records, it will only process records in FAILED or RETRIED status.
3. It will take all existing data and resubmit the record for processing, without change.  This allows the server to recover from temporary errors, such as the data source being temporarily unavailable.  If there were any errors with the data in the original transaction (validation failures / fields missing / etc.), reprocessing them will not result in successful processing, it will require investigation.
4. If the QueueJob was successful in processing the failed transaction, any records that were in Pending status (queued) waiting for the original transaction, will now be processed.
5. Once records have been processed, they are marked as READY and a notification to the client is queued.  When received, the client will display a success notification and remove the failed record from the sync log.  It will also clear the notification from the Sync Log icon.

Summary

It is critical that users monitor the failures / queued transactions by monitoring the following parts of the application.

• Page:
  Setting up multi-configuration
• Page:
  Multi-configuration structure / features
• Page:
  Multi-configuration Considerations
• Page:
  Multi-configuration Process
• Page:
  Multi-configuration servers