Troubleshooting

The goal of troubleshooting is to determine why something does not work as expected and explain how to resolve the problem. With this troubleshooting guide, we strive to introduce a troubleshooting methodology that helps administrators determine the cause of issues with Citrix Microapps.

The troubleshooting process involves understanding, specifying, and describing the problem completely. Accurate problem descriptions help you and Citrix Support know where to start to find the cause of the problem. During the process of troubleshooting you often find enough information to solve a problem, though it may not lead to problem resolution in all cases. The results of these procedures lead at minimum to a good description of the problem state, and that is the best way to start down the path of problem resolution.

Here’s an overview of the troubleshooting process:

  1. Establish a failure state: Can the problem be reproduced? If so, reproduce the issue and record the exact steps performed to reproduce the issue. If not, record key details. Finally, specify the behavior and determine the extent of the problem.

  2. Investigate and gather evidence: Isolate the platform from environmental issues. Look for clues and gather data from the Microapps builder, event log, the integration system of record (SoR), and identity provider.

  3. Provide a summary of results and contextual information to Citrix Support: After establishing a failure state and gathering evidence, if you haven’t found the cause, provide the results of the tests and contextual information to Citrix Support.

Now let’s take a more detailed look into each step in the troubleshooting process.

Establish failure state

If you have a reproducible issue, record the exact steps that you performed. Be as detailed as possible. If the issue cannot be reproduced, it is important that you record as much detail as possible about the undesired behavior. Then specify and determine the extent of the behavior.

Note:

Remember that an incremental synchronization must be run before the user can expect a notification card. Either wait for the scheduled incremental synchronization or run it manually.

Reproducible issue

For a reproducible issue, record the exact steps that you performed. Be as detailed as possible.

Let’s take this example of how the process to reproduce the issue of a notification card not showing up in a subscriber’s Workspace activity feed was documented:

Problem statement:

Workday notification to Approve Expense Report not displaying in User1’s Workspace activity feed.

Steps to reproduce (actual behavior):

  1. AdminA added Workday integration in Microapps builder.
  2. Successful full synchronization.
  3. Successful incremental synchronization.
  4. Configured Microapp Approve Expense Report.
  5. Configured Notification Approve Expense Report.
  6. Configured Feed Card settings - screenshot included.
  7. Subscribed User1 to Microapp.
  8. Applied the change to Workday that triggers the notification for the specific user.
  9. Requested Expense Report Approval for User2 who is a direct report of User1.
  10. User1 logged in to Workspace.
  11. User1 reported that they did not receive the feed card.
  12. AdminA ran the notification in Microapps builder.
  13. AdminA checked the event logs in Microapps builder.
  14. AdminA received the following error message (insert error text or screenshot).

Unable to reproduce

Reproducing the issue is not always possible. If the issue cannot be reproduced, it is important that you record as much detail as possible about the undesired behavior. Let’s take the same example as above, but where the issue is no longer occurring:

Problem statement:

Workday notification to Approve Expense Report not displaying in User1’s Workspace activity feed.

Steps to reproduce (actual behavior):

Record the steps that led to this issue, as detailed as possible.

  1. User2, who is a direct report of User1, requested an expense report approval from Workspace using the Workday Microapp on Friday (include date) at 2:30pm.
  2. User1 logged in to Workspace Friday (include date) at 3:30 pm.
  3. User1 reported that they did not receive the feed card.
  4. Feed card never displayed in User1’s feed.

View and document the current state of the undesired behavior.

  1. AdminA checked the event logs of the Microapps Builder for Friday at 2:30pm.
  2. Notification was successfully generated for User1 at 2:30:50 pm.
  3. AdminA saw no errors on Workday and did see the request from User2.
  4. The request was still unapproved.

Specify the behavior

Now, let’s specify the behavior. To narrow the scope of the issue and generate logical possible causes, it is important to understand more about the behavior and the extent to which the issue occurs. Begin by answering the following questions:

  • When did the issue start (try to get the timestamp to the second)?
  • Did this operation ever work previously?
  • If it worked previously, what changes have been made?
  • How often does this error occur (get dates/times of subsequent occurrences)?
  • Does it happen intermittently or sporadically (following a pattern/schedule or not?
  • Are all integrations affected?
  • Are all microapps affected?
  • Are all users affected?
  • Are all authentication types affected?
  • Is proper configuration in place?

Extent of issue

Determine the extent of the issue. You might not have the answers to all the questions above. It could be necessary to define some basic test plans to determine the proper extent of the issue. These tests vary depending on the type of issue being investigated. Importantly, make sure that any testing follows proper security, compliance, and performance guidelines and considerations.

For the notification issue, it might make sense to try some of the following tests to determine the extent and further specify the actual behavior:

  • Undo any changes made before the issue occurred.
  • Have User1 try a different browser.
  • Have User1 try incognito mode.
  • Try a different Workspace user account (similar to User1).
  • Try a different Workspace user account (similar to User2).
  • Try a different integration (SoR) user account.
  • Try a different integration (SoR).
  • Try a different microapp.
  • Try a different notification.
  • Use different, but similar, notification settings.

Investigate and gather evidence

There are some additional techniques that can be applied to gather more evidence to expose or support a possible cause. It is important to isolate Citrix platform issues from customer environmental issues.

Check for Citrix platform issues

For Citrix Cloud services like Microapps, be sure that there are no global outages affecting performance:

  • Navigate to https://status.cloud.com/ to see if there are any known outages.
  • Check in the Citrix Cloud Console (customer.cloud.com) for any Notifications of issues affecting the Cloud or the specific Citrix Cloud customer. Find notifications in Workspace
  • Make sure the Microapps service is enabled as a feed under Workspace Configuration:
    1. After signing in to Citrix Cloud, select Workspace Configuration from the menu.
    2. Select Service Integrations.
    3. Ensure that Microapps is marked Enabled. For more information including full details and screenshots of setting up Workspace Microapps, see Getting started.

Check for customer environmental issues

Verify that the integration is syncing properly. If you encounter an error with synchronization, verify account details:

  1. Check for errors with the integration. After signing in to Citrix Cloud, select Manage on the Microapps tile to open the Microapps admin console.
  2. In the Microapps admin console, check that the integration is synchronizing properly. Look next to the integration. You can see an error in this screenshot:

    Synchronization failed

  3. If there is a synchronization failure, check the integration logs. Select the menu next to the integration that you want to view integration logs for.
  4. Select Integration Logs.
  5. Take a screenshot or copy the error message, including the timestamp. Here’s a sample error message:

    Synchronization failed

    For more information about integration logs, see Set data synchronization.

  6. Now we need to run our integration synchronization again. Select the menu next to the integration for which you want to set synchronization and select Synchronization. How to set data sync
  7. Run an incremental synchronization. Check event log, and document any errors.
  8. Run a full synchronization. Check event logs, and document any errors.

    For more information about running data synchronization, see Set data synchronization.

If you encountered any errors with synchronization, verify the following details:

  1. Verify that the service account has proper permissions on the integration side (SoR). How to do this is unique for each SoR. For example for Workday, see Manage security group permissions.
  2. Verify that the service account credentials are valid in the Microapp console and in the SoR.
  3. Verify that the client ID and secret are correct (if necessary).

    For more information, see Set up service authentication.

Check the notification in the Microapps builder

Now you need to check the affected microapp. We’ll take the Workday Approvals microapp we’ve been working with as our example. Check the subscriptions and notification configuration, and run the event again to gather relevant UUIDs.

  1. First, let’s make sure User1 is subscribed to the notification. Select Subscriptions from the affected microapp’s menu. Checking user subscription
  2. Next, open the affected notification. Select Edit from the affected microapp’s menu and choose the failing notification.
  3. Verify the And notify configuration is correct: Verify notification configuration
  4. Preview Microapp to make sure it shows as expected. The following screenshot shows the location of this option and the next two. Preview, run, and show event log notification
  5. Select Run Event.
  6. After the event finishes running, select Show Event Log and select the drop-down menu of any error. Record any error message, record any relevant UUIDs (Notification ID or Transaction ID), and copy event log text to a txt file.

Check your integration (SoR)

  1. Check the integration SoR event logs for any details regarding the failure.
  2. Record any relevant information to supply to Citrix Support.

For more information, see Set up integrations.

Check identity providers

  1. Verify active directory or other identify provider is correctly set up.
  2. Verify authentication is correctly configured.
  3. Look for missing data, improper, or incompatible configurations and errors.

For more information, see Getting started.

Provide a summary of results and contextual information to Citrix Support

Include the results from the preceding sections and the following contextual information. Be aware of releasing sensitive data. For more information about sensitive data, see Microapps Technical security overview.

  • Exact time of the last known occurrence of the issue.
  • Affected integration (SoR) name as shown in the Microapps builder and the integration UUID from the Microapps console URL.
  • Affected microapp name as shown in the Microapps builder and the microapp UUID from the Microapps console URL.
  • Affected notification name as shown in the Microapps builder and the UUID from the Microapps console URL.
  • Affected user name (Workspace), email, and OID.
  • Affected user name (integration SoR).
  • The following details from the Microapps event logs:
    • Exact time of the last known occurrence of the issue.
    • Affected Card UUID.
    • Affected Transaction ID.
    • Error/Exception Details. Reproduce and record as shown above.