Troubleshooting Touch Apps

It is important to be able to troubleshoot mobile application issues such as:

Contents

Troubleshooting Mobile Applications

A Mobile Application will initially connect with IFS Applications and will download all data that the mobile user/application has access to. This process is known as Activation.

The data is then maintained on the Mobile Application by the Push and Batch synchronization processes as described in Synchronization Rules. These processes gather data for the mobile user/device/application/version and create Out Message records. These records are removed from IFS Applications once they are received by the mobile application.

When problems with mobile applications are experienced with data not being received or sent the following should be checked:

  1. Push Queue - ensure the push synchronization processes are running and no warnings or errors are being reported
  2. Synchronization Tasks - ensure the synchronization tasks are running and no warnings or errors are being reported
  3. Background Jobs - ensure the background jobs associated with the Synchronization Tasks are running and no warnings or errors are being reported
  4. Out Messages - ensure the Out Messages are being created and are being received by the mobile application
  5. Mobile Logs - ensure the mobile application is connecting
  6. Synchronized Entities - ensure the entities are being synchronized for the mobile user/device/application/version and that the entity has been synchronized as per the Synchronization Rules
  7. Synchronization Traces - enable Synchronization Traces per mobile user/device/application/version to check that no errors/warnings are reported in the synchronization process
  8. Application Parameters - ensure the data is being synchronized as per the application parameters defined for the application/version
  9. Custom Fields - ensure the Custom Field(s) are published and are displayed in Entity Details. Ensure security is granted for the UI Designer as defined here (end user documentation).  Ensure the mobile application has been initialized so the schema changes are visible in the UI Designer
  10. Failed Transactions - ensure no transactions exist in the Mobile Application Error Handling or Failed Transactions

 

Connecting to IFS Applications

When Activating a mobile application with IFS Applications the mobile user will be asked for a System ID and a potentially a Service URL if the mobile application is connecting via the Touch Apps Server. If the mobile application is connecting via the IFS Touch Apps Cloud then no Service URL is required to be entered.

The System ID will be defined when the Touch Apps Server is installed or the environment is registered in the IFS Touch Apps Cloud. The system administrator should be contacted for details of the System ID and Service URL.

If the mobile application cannot connect to IFS Applications then it is important to check that the device can connect to the Service URL via a web browser. If the mobile application cannot connect to the Service URL then the system administrator should be contacted.

Initialization

Initialization is an action that is performed by the mobile user after the Activation process has completed. This will remove the local database and re-download all data the mobile user/application has access to.

An Initialization will perform the following actions:

  1. Send Transactions to IFS Applications
  2. Delete any Failed Transactions in IFS Applications
  3. Delete the local database
  4. Re-download all allowed data

A Force Initialization will perform the following actions:

  1. Delete local Transactions
  2. Delete any Failed Transactions in IFS Applications
  3. Delete the local database
  4. Re-download all allowed data

 

Mobile Application Error Handling

Certain mobile applications are designed with client side error handling. When operating a mobile application with this design pattern then it is important the mobile users are educated on how to manage synchronization failures.

The errors will be displayed in the Synchronization Monitor as shown below:

Options exist in the mobile application to Resend, Edit or Delete the failed transaction as shown below:

The mobile user should be educated in how to handle failed transactions and the Resend, Edit and Delete processes.

Read Troubleshooting Failed Transactions for details on the types of errors that may occur.

Note: if client errors are not handled then no transactions will synchronize with IFS Applications so it is important that the mobile user deals with errors in a timely manner.

 

Troubleshooting Failed Transactions

Failed Transactions down into four main categories which are:

 

 Note: There is an Application Defined Event named MOBILE_FAILED_TRANSACTION which can be configured to alert administrators/end users when a Failed Transaction has occurred.

 

System Data Errors

System Data errors occur when the mobile application sends data to IFS Applications that is invalid. This is typically due to the mobile users data set-up or the IFS Applications data set-up. 

An example of incorrect mobile user data set-up is when the user is not defined against an Accounting Rules User Group. In this example when a mobile application sends a transaction that will create a financial transaction in IFS Applications the following Failed Transaction will be generated:

To correct System Data errors the IFS Applications data set-up should be amended and the Failed Transaction resent.

See Managing Failed Transactions for details on how to handle Failed Transactions.

 

Transaction Data Errors

Transaction Data errors occur when the mobile application sends data to IFS Applications that is unknown. As the mobile application can be offline mobile applications can allow data to be entered that is not known by the mobile application and instead allow IFS Applications to validate this when the transaction is synchronized.

An example of unknown data is when a new work order is created with an unknown equipment object.  In this example when a mobile application sends the new work order transaction to IFS Applications the equipment object will be validated and the following Failed Transaction will be generated:

To correct Transaction Data errors the IFS Applications data set-up should be amended to register the unknown data or the Transaction Data should be modified in the Failed Transaction Detail screen. The Failed Transaction can then be resent.

See Managing Failed Transactions for details on how to handle Failed Transactions.

 

Process Errors

Process errors occur when operational data in IFS Applications is amended after the mobile application has synchronized. This can be removing data from IFS Applications that the mobile application is altering or it can be amending configuration data in IFS Applications that the mobile application has no knowledge of.

An example of removing data is Unassigning a Work Order that has been transferred to mobile.  In this example if the mobile user updates the Unassigned Work Order the following Failed Transaction will be generated:

An example changing data can be seen by altering the configuration of a part in IFS Applications that the mobile application has no knowledge of.  So a Part that is not configured as Condition Code Enabled is synchronized with the mobile application.  After this point if the part configuration is changed to enabled Condition Code will result in the following Failed Transaction if the part is used in the mobile application before the part basic data is updated:

It is difficult to successfully resend Process errors so it is important the process is defined and the data set-up correctly before the mobile application is used.

See Managing Failed Transactions for details on how to handle Failed Transactions.

 

Software Errors

From time to time software errors cause Failed Transactions.  When these occur the error should be raised in LCS so that it can be corrected.

Until the software error is corrected the Failed Transaction should be Ignored or Deleted, depending on the importance and impact of Ignoring/Deleting the transaction.

See Managing Failed Transactions for details on how to handle Failed Transactions.

 

Consequential Errors

As mobile applications can be offline transactions are queued by the mobile application and synchronized when connectivity to IFS Applications is restored. If a transaction for a specific business object generates a Failed Transaction that has subsequent transactions altering the same business object then the subsequent transactions will be queued behind the Failed Transaction as shown below:

If the Failed Transaction cannot be resent and is instead Deleted then the subsequent transactions are likely to also generate Failed Transactions.

An example of a consequential error is the creation of a Work Order followed by changing the Work Order status.  On deleting the Work Order transaction then the subsequent state change transaction will fail as the Work Order will not exist in IFS Applications and will generate a Failed Transaction as:

In this example, if the mobile user continues to update the Work Order then it is likely that the following Failed Transaction will be generated:

It is therefore important to remember that after Deleting a Failed Transaction the mobile application data should be realigned with the server data.  This can be done by the administrator changing the server data to match the mobile application or requesting the mobile user to initialize the mobile application.

See Managing Failed Transactions for details on how to handle Failed Transactions.

Troubleshooting Synchronization

There are several actions on both the server side, and the client side, that can be used to effectively troubleshoot Synchronization issues. These issues may vary, but typically involve the following:

Slow Synchronization times

Data not being received by the client app

Data returned from the client app not appearing in IFS Applications

Client Investigations

There are some limited troubleshooting steps that can be taken on the device to look at Synchronization problems. They include:

It is possible to examine the local database on the client. This may help to identify any data format related issues that could be having an impact on client side Synchronizations.

It is also possible to look at the client app logs, to see if any errors are being recorded on the client side, that may be affecting Synchronization processes.

Examining the status of the Sync Monitor – is it possible to connect to the server, or not? Are there pending transactions showing on the Sync Monitor?

These are the only steps that can currently be taken from a client perspective, so the primary focus of our troubleshooting will be server side investigations.

Server Investigations

There are several server side tools that can be used for troubleshooting Synchronization issues:

Test Initialization

It is possible to perform the option Test Initialization from Installed Apps/Devices that will create a new "dummy" device for the select User, App and App Version and perform an initialization. On selecting the Test Initialization option a prompt will be shown to navigate to the Background Job that will process the initialization request.

Once this request is completed the results will be shown in the Logs, Synchronized Entities and Synchronization Traces (if enabled).

Note 1: The "dummy" device will not be included in the batch sync process. This is for testing the performance of the initialization request for a single user.

Note 2: It is best practice to remove "dummy" devices using the Delete App/Device option when the test results have been analyzed.

 

Synchronization Tracing

Permissions to run Synchronization Tracing are enabled when the user is granted the FND_TOUCHAPPS_SYNC_TRACE permission set, which grants the user the system privilege of “Debugger”. With this in place it is possible to setup tracing for a single device in IFS Applications. This can be found in either Mobile User Details or in Installed Apps/Devices which will generate a trace including all the information about a client connecting, and all the database processes running in relation to that client, including the PL/SQL Statements that are being run. This can provide a large amount of information in relation to specific client issues. Given the amount of data this generates, it is important to run the Schedule Task to clean-up Synchronization Traces if this is left running for a long period. Also, due to the volumes of data generated by a trace, enabling tracing for all devices in a large device community is NOT recommended.  It is recommended that tracing is set for devices with issues only.

 Device tracing can be found in Synchronization Tracing in IFS Applications:

When examining the trace logs using a key word search is the best way to find issues that have been recorded. This could involve searching for a key word of “error” for example, or searching on an entity name that you know is causing issues.

Database Processes

It is possible to examine the background process that produces Push Queues and Synchronization Tasks to ensure it is working correctly in IFS Applications (Mobile_Sync_SYS.Process_Push_Data). The process will indicate whether there have been any failures to process data, Time last run, and time taken to run the process. This would also help in identifying any slowdown in database processing as an impact on Synchronization delivery.

Push Queue

In the Push Queue, it is possible to see the creation of push queue records for every IFS Application database entity that is changed, and is to be synchronized to Mobile. There have been several changes to this in recent versions:

Synchronization Tasks

In terms of trouble shooting Synchronization issues, it is also possible to check the Synchronization Tasks list in IFS Applications, which will provide information on how long it is taking to run Synchronization Tasks and produce the background jobs that will create the actual out message that will then be sent to the Mobile Device. In the Sync Tasks list you can see if a task has completed, and get information on how long that task took to run for all entities listed. If completed you can also RMB and view the Background Job that has been created by the Sync Task to produce an Out Message.

Background Jobs

The Background job that has been created to produce an Out Message with Push or Batch Data for a mobile application can also be viewed in IFS Applications. If you view the background job, you will see the associated Sync Tasks at the bottom, and whether the background job has been executed, and how long it took to execute, which can also be useful when troubleshooting slow sync times for a customer.

User/Device Logs

It is possible to view the Mobile Logs related to a sync task, which provides a further level of information in relation to the sync task. The user/device logs will tell you when processing started for a specific entity in the sync task, and when processing finished. This means that it is possible to troubleshoot whether custom changes to a database entity are affecting the Synchronization process, which might be visible if for example the changes are increasing the processing time for a specific entity, compared with other elements of the sync task.

We also write to the logs if a single entity sync takes more than “x” seconds to complete. This is configurable in System Parameters and provides additional visibility of synchronization issues that are connected to issues with an entity and related customizations.

In addition, in the mobile logs you will find a message with the comment “push data found”, as per the screenshot below. This confirms that an Out Message has been produced to be sent to the mobile user/device.

Synchronized Entities

It is possible to view Synchronized Entities, which will provide information on when an entity was last synced, and give a duration for the last sync.

Out Message Queue

The Mobile Logs will confirm the production of an Out Message, and it is also possible to look in the Out Message queue and view the message that has been created . You can also select a specific Out Message and view the data that is being sent to the mobile application (using Right Mouse Button). Out Messages are created as either insert, update or delete messages, and once processed you will see the results in the mobile application data.

System Parameters

There are several System Parameters that can be set in relation to synchronization processes.

Checking Synchronization Data Volumes

It is possible using SQL queries to check the Synchronization data volumes for either a single active user, or for all users. The SQL statements for querying this data are as follows:

To check data volumes for a single Active User of a mobile application:

SELECT msd.user_id, msd.device_id, msd.entity, count(1) as "Record Count" FROM ifsapp.mobile_sync_data msd, ifsapp.mobile_device_app_user mdau WHERE upper(msd.app_name)=upper('&Appname') AND   mdau.app_name=msd.app_name AND   mdau.device_id = msd.device_id AND   mdau.user_id = msd.user_id AND   msd.user_id = upper('&userid') AND   mdau.state_db = 'ACTIVE' GROUP BY msd.user_id, msd.device_id, msd.entity ORDER BY msd.user_id, msd.device_id, msd.entity

To check data volumes for all users of a mobile application:

SELECT msd.user_id, msd.device_id, msd.entity, count(1) as "Record Count" FROM ifsapp.mobile_sync_data msd, ifsapp.mobile_device_app_user mdau WHERE upper(msd.app_name)=upper('&Appname') AND   mdau.app_name=msd.app_name AND   mdau.device_id = msd.device_id AND   mdau.user_id = msd.user_id AND   mdau.state_db = 'ACTIVE' GROUP BY msd.user_id, msd.device_id, msd.entity ORDER BY msd.user_id, msd.device_id, msd.entity

Grouped Push Synchronization Process

The Grouped Push Synchronization Process writes all logging information to Grouped Push Transaction Traces. The trace information here consists of data related to the Initialization of Grouped Push Datasets, the maintenance of Grouped Push Datasets and the main Grouped Push Database Process. The logging level for each of these can be changed via the Application Parameters INIT_TRACE_LEVEL, TRIGGER_TRACE_LEVEL and BATCH_TRACE_LEVEL.

Note 1: Trace levels INFO, TRACE and DEBUG may generate huge number of records in Grouped Push Transaction Traces. It is therefore recommended to not leave these parameter set to any value other than STAT or WARNING for longer than a few hours.

In addition to the Grouped Push Transaction Traces the Grouped Push Transaction Queue will also report errors generating or maintaining the Grouped Push Datasets. The Error information will be shown directly in the Queue record.

The Grouped Push Filter Map shows the WHERE statements used within the Grouped Push Synchronization Process to fetch the Grouped Push Datasets for the User. These WHERE statements can be used to determine what data should have been synchronized to the mobile user. They also indicate if the mobile user has permission set granting to synchronize the entity data. If the details shown in Grouped Push Filter Map do not match with what is expected then it could be that the Mobile Applciation Cache has not been refreshed. This is possible via the Refresh Server Cache process.

There are Application Defined Events named GROUPED_PUSH_FAILED and GROUPED_PUSH_BACK_TO_NORMAL which can be configured to alert administrators/end users when issues arise in the Grouped Push process. These events include a MESSAGE field which states either "Group Push Synchroinzation failed" or "Groupe Push Synchronization back to normal" and a TASK field which states the sub-process of INIT, REFRESH or PUBLISH.

Post Database Cloning Activities

If the database is replaced with a clone (say replacing Test with a copy of Live) then to ensure the Mobile Applications/Touch Apps are working again then the following activities must be performed:

  1. The IFS Touch Apps Server that is used to connect to the environment must be reconfigred. This is because the TAS configuration (for Push Notifications etc) are stored in the database. The TAS must therefore be re-aligned with the replaced database.
  2. If Grouped Push is in use then the grouped push data will be invalid in the replaced database. To remove this a script must be run calling "FNDMOB_DEPLOYMENT_SYS.Post_Db_Clone_Cleanup" (this procedure has no paramerters).
  3. All Apps must be re-initialized to ensure they are synchronizing data from the replaced database.