Universal GUI troubleshooting

Troubleshooting Universal GUI setup

tip

Make sure you know the differences between the Universal GUI and other GUIs. These differences are by design and can explain different behavior from your previous GUI. See Differences between Universal GUI and other GUIs.

• Validate the model. The Universal GUI is sensitive to incorrect models.
• Download and install the latest Universal GUI and Indicium service tier and run all upgrades and hotfixes on the SF and IAM.
• Try running the Universal GUI and Indicium on the same server. The domain name for both URLs must be the same.
• Use fully qualified domain names, like server.thinkwisesoftware.com/indicium instead of server/indicium.
• Test access to Indicium by accessing the URL directly with the used credentials.
• Clear the cache of your browser. Alternatively, try incognito mode.
• If possible, update your browser or switch to a recommended browser.
• Ensure the user has access to the application in the Intelligent Application Manager or the runtime configuration in the Software Factory.
• Ensure a list bar menu, tree menu, or tile menu is available to the user.
• Ensure that a default theme or menu is set.
• Run the Correct foreign key casing task in the Software Factory and re-synchronize with IAM if needed to prevent casing issues.
• Ensure the MIME types are configured correctly on the webserver.

Tools for troubleshooting Universal GUI

This chapter describes some best practices in troubleshooting the logic executed by the Universal GUI's backend and its interaction with the Indicium data/service layer. The tools mentioned can bring you up to speed with solving unexpected errors and situations where a user process doesn't run as expected.

Model insight

If you have been configured as a developer in IAM, you can use Model insight to find out which column, table, and variant you have selected in the Universal GUI.

Use the profile menu or press ALT+F1 to open and close Model insight.

Open model insight

If no screen is opened and no column or screen is focused, the Model insight screen will be empty. You can move Model insight by dragging it.

Whenever you open or resize a subject, breakpoint information is displayed briefly at the bottom left of the subject.

Due to technical limitations, Model insight is not available for the HTML control and the card list.

Selected column, variant, and table

DevTools for troubleshooting

The Universal GUI is a web application. Therefore, you can use the developer tools delivered by modern browsers to get a lot of information about what is going on in your application. This chapter focuses on the tools for the Chrome browser. Other browsers offer similar tools, so you can choose the browser you prefer.

1. Open the Universal GUI as a website or an installed app on your PC's desktop.

2. In both cases, open the developer tools by pressing the F12 shortcut from within your application.

3. To get more room to see all the information, disconnect the tool as a separate window and move it to your second monitor.

   At the top, you will find a navigation bar with several buttons and tabs:

Navigation for the Chrome developer tool

• The first button and the Elements tab work together. Use the button to inspect (HTML) elements.
• With the second button, you can simulate different mobile devices for your application. This can be helpful when you want to test screen type breakpoints modeled in the Software Factory. A new toolbar will be displayed:

Mobile device toolbar for testing breakpoints

• One of the most interesting tabs is Network:

  The Universal GUI operates fully in the browser of the client, it knows nothing about the application to open. The definition of the application is requested from IAM through Indicium by so-called I_UI views. These views deliver the definition filtered by the logged-in user (rights) and the configured platform in the login page. Only the definition required for the actual user action is loaded, called Lazy Model Loading. The Network tab shows a lot of these requests when the GUI or a subject is opened for the first time, all getting a specific part of the application's definition.

Example requests

So, this overview shows all requests with some details about each one, like the response data size and the duration. The HTTP status column indicates whether the request was successful or not.

• Informational responses (100–199)
• Successful responses (200–299)
• Redirects (300–399)
• Client errors (400–499)
• Server errors (500–599)

The most common responses for our type of application are:

• 200, 204 - successful request.
• 400 - the request URL is constructed incorrectly by the GUI or contains unexcepted values, e.g., an empty PK column value.
• 401 - unauthorized. The user is not logged in to Indicium (anymore). Note that the login page will execute i_ui_user before login to validate whether the user has logged in or not. This may cause a 401 error on purpose if not.
• 403 - the client is not allowed to access an entity from Indicium. Usually, this should not happen when the definitions of the GUI and Indicium are in sync.
• 404 - happens when the entity does not exist.
• 409 - a data conflict occurred, e.g., when multiple users are editing the same record.
• 422 - the request was successful, but the operation was not allowed, e.g., a validation error when an edited value is processed.
• 500 - an internal error on Indicium's side.

More information is in Indicium's log file. A developer-friendly error is printed there along with the stack trace of the Indicium code. This message may clarify the cause of the problem. If necessary, this is also valuable information for Thinkwise to attach to a TCP support ticket.

1. Click on a (faulty/red) request in the Network tab to get more details about it. Here you get to see all the details about how the Universal GUI and Indicium "talk" to each other. Details about this are well documented online here.

Example network details

What's important here is the URL at the top, including all users, (pre)filters, sorting, and everything else the Universal GUI adds to it to get the desired information. See also Common OData requests in the DevTools and the OData API as used by Indicium.

The reaction from Indicium is in the Preview and Response tabs. At the bottom of the Response tab is a button available to format the one-liner of JSON data.

Example network details response

The top toolbar of the Network tab offers options to filter, stop, clear, and export (as a HAR-file) the network request logging the Universal GUI is sending to Indicium while working in it. This can help create an image of a situation or process that does not demonstrate the desired behavior. It is also helpful information to attach to a TCP support ticket, if necessary.

Network tools

Common OData requests in the DevTools

This chapter will clarify the most common requests in the DevTools' Network tab.

• Every request starts with a base URL pointing to the desired application or database.
• After the base URL, the subject is specified.
• If Indicium needs to know the path from where a subject is opened, a navigation path is added.

https://<base_url>/indicium/iam/<gui_appl_id>/<tab_id>(<pk_col>=<value>)/detail_ref_project_sub_project?$orderby=...

For example:

https://testsite.com/indicium/iam/26/project(project_id=1)/detail_ref_<tab_id>_<detail_tab_id>?$orderby=...

note

If a request URL becomes too long to send it successfully to Indicium, the Universal GUI will convert it to a $query POST request and put the rest of the request in its body.

The Universal GUI lazy loads the application definition. It requests the i_ui_... views in the Software Factory and IAM to know what the application should look like. These views are, in general, called once for an unvisited subject.

https://<base_url>/indicium/iam/iam/i_ui_...?$filter=(gui_appl_id=x)...

• Login - When the login page opens, the Universal GUI requests Indicium with an i_ui_usr call whether the user has already been authenticated to Indicium. If so, login is skipped. If the user has not been authenticated (status 401 in the DevTools), the login procedure starts. A successful login is followed by a /login request and a set of global i_ui calls. Then the main page and its menu are shown.

• Open document - After opening a document from the menu, a set of i_ui views are requested for loading the subject and components definition. Meanwhile, the Universal GUI starts loading the dataset, followed by similar expand requests loading the presentation values of lookup columns. The requests involved for loading the dataset differ, based on an applied top-statement or paging mechanism. In the case of paging, multiple statements come by:

  • A seek request will look up the page containing the active record.
  • A count request is triggered to know how many pages should be shown in the paging bar.
  • With the result of the seek request, the actual page data is requested.

• Aggregations - In some places, the Universal GUI uses aggregated data. For example, in grid footers and for calculating totals in cubes and charts. These calls will be executed just after the request for the subjects' dataset has finished.

• Edit - When data is edited in the Universal GUI, Indicium reserves a staged resource to record all changes. Also, the results of the Default and Layout stored procedures are stored there.

  • After the user triggers an edit action in the Universal GUI, a staged resource is created. It is followed by a layout() and a GET request to check the result of the initially executed application logic, like default values and field or button visibility.

  • If a user changes a value in a field, the Universal GUI lets Indicium know by sending a request with method PATCH. This returns a response whether the staged resource has changed. A layout() and a GET request will follow when necessary.

  • For a lookup column, the PATCH is replaced by a call to the choose API. Lookup controls are filled by requesting all possible options from the lookup table using a list_ call.

  https://<base_url>/indicium/iam/<gui_appl_id>/stage_project/list_activity_id?$orderby=...

  When the user has finished editing, the staged resource is either committed (saved), or cancelled.

  If you want, for example, to run a load test or follow an edit session, it is good to know more about the process running in the background: Indicium issues a GUID when a staged resource is requested. This code is always sent with the GUI, so Indicium knows to which staged resource the request belongs.

• Tasks/reports - Executing tasks and reports, and changing parameter values also use Resource staging as described above. On a commit, the task logic will be executed or the report generated and downloaded. If multiple records are selected, an add_context request is included to let Indicium know about the selection. For more details, read the error handling for multi-row task execution.

• Process flows - In the Universal GUI, only one process flow is allowed to be executed on the same opened document. A Universal GUI connected to Indicium only knows about the start actions of the process flows available for this application. Indicium becomes the owner of the process flow and decides what will happen next.

  • If the Universal GUI detects a starting point, it requests Indicium what to do next. Indicium returns a location response header that the Universal GUI can use to continue the flow, by requesting for follow-up suggestions.

  • In some cases, Indicium will start the flow. For example, after an edit or task execution is commited and the location header returned. The Universal GUI leads the user to the suggested action and registers when it is finished.

  • When the suggestions are executed, the Universal GUI signals Indicium with a continue POST request. This request contains a status_code that lets Indicium know whether the suggestion succeeded or not. While executing a suggestion, all types of requests will come up.

  • The flow will continue until Indicium returns the PendingProcessAction response header on fetching new suggestions.

  If you want, for example, to follow a process flow session, it is good to know more about the process running in the background: Indicium issues a GUID when a staged resource is requested. This code is always sent with the GUI, so Indicium knows to which staged resource the request belongs.

Redux tools

The Universal GUI uses React components. For the interaction between the GUI and React, we use Redux state management. This combination offers the advantage that the browser tools can show what happens in the backend of the Universal GUI.

1. First, install the necessary browser extension:

   • Google Chrome
   • Microsoft Edge
   • Mozilla Firefox

   When installed, a new tab appears in the browser's Developer tools, called Redux.

New tab: Redux

2. A single click in your application triggers multiple actions on the left.
3. Select an action to show its details on the right.
4. Click on the selected action again to display the actual state of the last executed action in line again on the left.

To clarify the details:

• Action: shows the input of the actions, e.g., the subject to which the action belongs.
• State: shows the actual state of the entire GUI at the time the action was triggered. The mapping of the state is:
  • ui - the general state of the GUI. Most important is the documents -> contexts part that holds the state of currently opened subjects. Besides that, there is a global and menu context upfront. Also, a running task or report will claim an entity here. More information is available there.
  • staged - state of subjects that are editing data or executing a task or report.
  • processflows - state of runtime running process flows, like follow-up actions.
  • model - all lazy-loaded application definitions of visited parts of the GUI.
  • auth - current state of the user's authentication.
  • browser - helpful to know about the browser instance.
  • offline - all states that are required to work offline in the GUI. For example, pre-fetched data, pending changes, and the state of the GUI.
• Diff: shows the state changes caused by the execution of this action. Notice that many actions without state changes will be followed by a success or failed action that does the mutations. For example, when a request to Indicium is required.

You can filter the actions at the top of your screen. For example: you can find all process flow actions with [ProcessFlow].

note

This tool will only show the last x actions. You can configure this number with the Settings button right below.

Troubleshooting Universal GUI and Indicium (DB logging)

Indicium converts calls to one or more database statements to gather the information requested by the caller. So, if one of the tools (DevTools or Redux tools) described above points towards a problem with Indicium, you can consult Indicium’s database log.

To get an overview of the SQL statements executed by Indicium, you need to be marked as Developer in IAM (menu Authorization > Users > tab Administrators > tab Developer mode).

Then, you can access the database log:

• with a link on Indicium's landing page while being logged in.
• from the user menu in the Universal GUI.

Links to log file in Indicium

Agent

In this landing page, the Agent field is the Agent ID of the Indicium instance. This Agent ID corresponds to the IDs that you can find in IAM: Advanced menu > Logging > Agent check in.

It can help you troubleshoot issues regarding system flows. You can also use the Agent ID to test if your load balancer's sticky sessions configuration is working by refreshing the landing page a few times and checking whether the Agent ID stays the same.

Error log

If the DevTool shows an error 500, you can find more information in Indicium's log files.

Event viewer

If the DevTool shows an error 500, you can find more information in the Windows Event Viewer in Windows Logs > Application.