As more companies look to modernize their workspace experience, many are finding intelligent features essential to driving productivity and a great employee experience. Companies tend to leverage several cloud-based systems, from access and identity solutions to day-to-day applications, as part of these intelligent solutions.

In my previous blog post on implementing intelligent workspaces, I covered the technical and non-technical aspects of an implementation. Because there are several moving parts, I thought we would need a methodical approach to troubleshooting to drive customer success. Troubleshooting is a effort that can involve multiple teams and multiple technologies. The key to success is to understand when and where to escalate.

In this blog post, I’ll provide you with end-to-end troubleshooting guidance, from a help desk ticket all the way to resolution. We’re always happy to work with you to ensure your success, so never hesitate to contact Citrix Consulting for a helping hand!

Troubleshooting typically falls into three categories:

  • Authentication and Identity Provider
  • System of Record Permissions
  • Microapp Builder Logic

Each of these items typically falls under its own team in an enterprise organization, so it’s good practice to have an established ticket routing system that goes to each of these teams. You can even build a Citrix Workspace notification card using ServiceNow to route requests to these different teams. Let’s look at troubleshooting concepts for each of these categories.

Authentication and Identity Provider

End users need permission to access a system of record (SoR) defined at the identity provider level. For example, if Salesforce is front-ended by a system such as Okta, the end user will need to be added to the Salesforce app within Okta. Though this may be simple, I know we’ve all seen tickets like this come through. It’s a quick fix, but it’s important.

A more advanced concept is OAuth permissions within the SoR. Citrix Workspace leverages OAuth to make writes on behalf of the user. Typical to most OAuth2 flows, there is an access token and a refresh token. The access token is used to make the write, whereas, while the refresh token is used to provision a new access token.

More often than not, if an end user is frequently prompted to re-provision the OAuth tokens (in layman’s terms, press Authorize) within the SoR in a short period of time, double check your OAuth settings within the SoR. Validate that the appropriate settings are configured for provisioning/refresh and that security posture is balanced with user experience. For more information on the auth flows, check out this Citrix Tech Zone article.

System of Record Permissions

When it comes to a System of Record, your team should expect the same write permissions within Citrix Workspace as they would in the traditional SoR GUI. This means that if a user does not have permission to Create a Task within Salesforce, they should not be able to Create a Task within the Salesforce Microapp. The ultimate takeaway here is to subscribe your microapps accordingly to mirror what’s already assigned within the SoR.

On the other hand, all reads into the microapp cache are done using a service account. If certain records appear to be missing, there’s a chance that the service account might not have permissions to read those records. Alternatively, the culprit could be a table schema filter query, which we will cover in the next section.

Lastly, a key concept within microapps is that all record matching is done by the end-user’s Active Directory email attribute. This means that for notifications (and certain pages) to function properly, a user’s email needs to be attached to the record. I typically see issues when an end user’s Active Directory email does not match the one in a SoR.

The email matching could be problematic for extending notifications to managers or other employees “watching” records. This is because the email needs to be directly assigned to the record (or accessed via a table join). Using external technologies such as Azure App Functions with data ported into Azure SQL, you can perform cross-SoR joins to join emails to a variety of records.

Microapp Builder Logic

As with any form of technology, sometimes the problem is user error. Be sure to check your microapp/notification logic to validate that it works as expected. If you’re using an HTTP connector, validate that your endpoints are correct and that you are passing in the proper parameters.

We recommend a three phased deployment — dev, QA, and production — to make sure that all microapps, pages, and notifications go through checks and balances. Here’s a list of logic implemented and common places for error:

  • Pages
    • Table search filter
    • Page logic for showing, hiding, disabling, etc.
  • Notifications
    • Conditions when a notification fires off
    • Email matching
  • Table Level – Schema filters
    • Narrowing the schema filter to optimize performance and balance security
    • Not pulling in the relevant tables
    • Incorrect HTTP endpoints or parameters

Troubleshooting Methodology

Now that we identified several areas where an issue can occur during implementation, let’s look into a repeatable methodology you can use to troubleshoot end to end.

This troubleshooting pyramid represents where the majority of issues will be caught in a production environment. Using this chart, work from the bottom up to find a resolution. The idea behind this is that the items near the top are usually caught during the dev and QA deployment pipeline. The bottom items are most likely specific to the production environment.

WSi Troubleshooting pyramid

You may have noticed the term Troubleshooting Page in the pyramid. This is a key troubleshooting technique I learned from my colleagues and domain specialists Greg Hayes and Nicholas Holmquist. The concept is to create a non-user facing page and add a blank table like the one in the below screenshot.

Using this table, we can set filters to explore the data stored in the cache. This effectively gives us full transparency to the data pulled into Citrix Workspace and will let us know if data is missing. Ideally, you would want to create one troubleshooting table per schema table; however, to keep organized I typically stick with one and repurpose it for different data tables. Some key takeaways are:

  • If the data is in cache, the issue is likely on the page/notification logic.
  • If it is not in cache, the issue is likely in the table – schema logic or service account permissions.

When working with troubleshooting tables, keep in mind NDA/compliance-related items such as PII. Usually, this isn’t an issue outside of HR microapps, however, it is always good to double check with the SoR owners.

Finally, the decision trees below show the general troubleshooting flow. This is broken down into both reads and writes. The term DIP means Data Integration Provider, and references the SoR connector. Click the graphics to view larger.

Reads:

Write: