POC Guide: How to connect PowerBI with DaaS Monitor using OData and API clients

Overview

As a Citrix DaaS customer, it’s typical that more than one monitoring tool is being used within your organization. Different teams use different solutions - one team might monitor infrastructure components while another is responsible for security and threat hunting. The need for observability and centralized dashboards is high on your wishlist. Citrix has a way to help! This POC Guide shows you how to build a basic dashboard. While we’ll use PowerBI, this can be any solution of your choice, capable of connecting and fetching data via OData.

For better readability and documentation, the keys and secrets in this blog aren’t blurred. The customer-tenant ID, key, and secrets in the screenshots are invalid - always replace them with your connection details.

Create an API client in Citrix Cloud

The first thing to do is to create an API client. A Citrix Cloud account is required to use Citrix Cloud Services APIs. If you’re a new administrator, you must ask an existing Citrix Cloud administrator to invite you and grant permission to Citrix DaaS, Identity and Access Management, or otherwise create an API client for you. Log in to Citrix Cloud to get started. Once you have access to Citrix Cloud, follow these steps.

1. In the Citrix Cloud console, click the menu in the upper left corner of the screen.

    

   

    

2. Select the Identity and Access Management option from the menu. If this option does not appear, you may not have adequate permissions to create an API client.

    

   

    

3. Select the API Access tab.

    

   

    

4. Name your Secure Client meaningfully so other Cloud Admins can later tell what this key is used for - for example, PowerBI-Dashboard, and click Create Client.

    

   

    

5. The following message appears: ID and Secret have been created successfully. Download or copy and save the Client ID and Secret. You’ll need both to access the APIs.

    

   

    

6. After closing the previous dialog, take note of the customer ID in the description above the Create Client button or at the CCID label in the top right corner of your screen. You’ll later need this to access the APIs.

    

   

    

Create a Bearer Token - Manually

First, test if we can authenticate and fetch data. Maybe there’s a proxy or firewall restriction in place that you aren’t aware of. We keep things simple to avoid unnecessary troubleshooting. There are two ways to do this: using the developer portal and API explorer or using the command line.

Using the API explorer

1. One of the simplest ways is to open our developer portal and make use of the Invoke API function.

    

   

    

2. After clicking Invoke API, click the Authorize button. A popup appears asking for the Client ID and Client Secret that was downloaded in earlier.

    

   

    

3. When you click Generate, the form provides a bearer token for authentication. When you triple-click or single-click and CTRL+A, you can select and copy the bearer token.

    

   

    

4. If you used this method, take a copy of the bearer token to a temporary notepad for simplicity. Notice that the token has the format CwsAuth bearer= before it starts with the token itself. It’s also important to remember that Bearer tokens are typically valid for an hour, after which they expire. Follow the same steps to generate a new token if this token turns invalid during this process.

Quote

Note:

By the end of this guide, PowerBI will automatically create tokens.

Using cURL

We’re using GIT for Windows and Git Bash, which comes with this bundle. You can also download a cURL client or Linux on Windows or whatever option suits you best. The commands will likely be the same.

1. Run this command after replacing the US with your region (US, EU, AP-S, or Japan cloud api.citrixcloud.jp), the client_id, and the client_secret with the details you created earlier.

   curl 'https://api-us.cloud.com/cctrustoauth2/root/tokens/clients' --data-raw 'client_id=a7bd32de-h6c6-41d8-9138-d24354fb758a&client_secret=B9bhC3cn_08Ot9axi_5cgD==%3D%3D&grant_type=client_credentials'

   Quote

   Note:

   Other than using the browser method, you’ll get access_token beginning with ey.. and must manually add CwsAuth bearer= in front.

2. If you used this method, take a copy of the bearer token to a temporary notepad for simplicity.

Connect to Citrix Cloud with Power BI

1. Prepare the connection details, as you must use them multiple times.

   • Take note of the supported API Gateway endpoints for your region. Use one of the following endpoints based on your selected geographical region while accessing the Citrix Monitor Service data.
   • Put the URL into the same notepad where you already have a copy of your bearer token.
     • US region:https://api-us.cloud.com/monitorodata
     • EU region: https://api-eu.cloud.com/monitorodata
     • AP-S region: https://api-ap-s.cloud.com/monitorodata
     • Japan region: https://api.citrixcloud.jp/monitorodata

2. In that same notepad, copy the Customer ID / CCID from earlier - in our example screenshot, it was dcint216d0e6.

3. Start PowerBI and open with an empty workspace / new report

    

   

    

4. Click Get data from another source and select Web by clicking connect.

    

   

    

5. Select Advanced and replace the content as described.

    

   

    

6. For the first connection test, we’ll connect to https://api-us.cloud.com/monitorodata, which provides us with a list of all available resources. This way, we avoid query typos and get an excellent overview simultaneously.

7. If you followed these steps in less than 60 minutes and your firewall is allowing you to connect to Citrix Cloud, you now see a screen like this:

    

   

    

8. Repeat the same connection steps for each table you’re interested in by appending /DesktopGroups for Desktops, /Sessions for Sessions or /Users for the Users table. For now, keep it simple. Shortly, we automate the bearer token creation process.

9. For our example, we’ve created the following tables and relations:

    

   

    

10. This connection will already allow us to create some basic visualizations.

     

    

     

Let PowerBI create the Bearer token using a function automatically

First, we must create a function within PowerBI and then update our sources to call this function instead of using the Bearer token.

1. Create a Blank Query

    

   

    

2. Name the Query GetAccessToken (right menu pane/properties) and put the following content in the query:

    let
    tokenUrl = "<https://api-eu.cloud.com/cctrustoauth2/root/tokens/clients>", // get citrix cloud API credential (bearer token)
    headers = [
    # "customerid" = "the-ccid-from-step-1", // CCID displayed in citrix cloud tenant
    # "Content-Type" = "application/x-www-form-urlencoded", //format for powerbi
    # "Accept" = "*/*"
    ],
    postData = [
    grant_type = "client_credentials",
    client_id = "the-long-customer-id-from-step1", // here your API key from cloud.com identity
    client_secret = "the-short-secret-from-step-1" // here your API secret
    ],
    response = Json.Document(Web.Contents(tokenUrl, [Headers = headers, Content = Text.ToBinary(Uri.BuildQueryString(postData))])),
    // get the CC bearer token from the response and add the in header expected 'CwsAuth bearer' in front
    access_token = "CwsAuth bearer=" & response[access_token]
    in
    access_token

Your result should look like this:

1. Using PowerBI Advanced Editor, modify your existing queries to use the new function.

   • Depending on your PowerBI settings and whether you’re used to doing this, you may get a Formula.Firewall: Query references other queries or steps error message.

    

   

    

   • A quick fix is to click in PowerBI File > Options > Privacy > and select Ignore the Privacy Levels.

    

   

    

2. In Power Query Editor, right-click any existing queries and select Power Editor.

    

   

    

3. Delete and replace the bearer token in your query with the newly created function GetAccessToken. The line should now say Authorization=GetAccessToken, without “ “ or ()

    

   

    

4. After clicking Doneand Close & Apply, your new function and the updated query should fetch a new token and update the content successfully.

When you’ve confirmed this step is working successfully, you can update the other queries you’ve added previously to make use of the function, too.

Summary

You may have noticed that there are certain limits in place.

Permissions

The permission required in Citrix Cloud to run the OData queries against the Monitor API is, at minimum Read Only Administrator. For more details, see our Data Access Privilege documentation.

Pagination

The monitor API returns 100 records per call, so if your script is designed to query more than 100 records, you need to modify the script to handle pagination or to filter the results correspondingly, for example, using a live query.

Data Granularity and Retention

Citrix Monitor stores and aggregates different types of data with different granularity. It’s essential to know the data granularity to understand the results you’ll receive when using the Monitor API to retrieve data.

For example, the SessionMetrics data, which includes session RTT, is only available for one day, while the sessions themselves are available, by default, for 90 days if you have Premium Edition and 31 days with Advanced.

This is because Citrix Director and Monitor´s purpose is real-time troubleshooting and triaging of sessions for help desk teams.

Here, you can learn more about Monitor Data Retention.

Looking for historical insights and analytics?

Currently, a Citrix Analytics OData connection in private preview provides you with 13 months of historical data and more insights. This requires you to have Citrix Analytics in place, which at the same time gives you even more metrics from various connected sites.