PowerBI Connector

The PowerBI connector allows you to integrate your Microsoft PowerBI workspaces and datasets with TextQL, enabling Ana to query and analyze your PowerBI data directly. This connector uses Azure Active Directory (Azure AD) application registration for secure authentication. With the PowerBI connector, you can:

• Discover and sync reports and datasets from your PowerBI workspaces
• Query your PowerBI data using natural language through Ana
• Get insights from your PowerBI reports and visualizations

​

Prerequisites

To set up the PowerBI connector, you’ll need:

• Administrator access to your organization’s Azure portal for app registration
• Workspace admin access in PowerBI to grant permissions
• PowerBI Pro or Premium license

​

Step 1: Azure AD App Registration

First, you need to create an Azure AD application registration to obtain the required credentials.

​

1.1 Navigate to Azure Portal

Go to https://portal.azure.com and sign in with your organizational account.

​

1.2 Create a New App Registration

Navigate to Azure Active Directory > App registrations and click + New registration. Fill in the registration form:

• Name: Choose a descriptive name (e.g., “TextQL PowerBI Connector”)
• Supported account types: Select “Accounts in this organizational directory only”
• Redirect URI: Leave blank (not required for service principal authentication)

Click Register to create the application.

​

1.3 Copy the Tenant ID and Application (Client) ID

After registration, you’ll be taken to the application overview page. Here you can find two critical pieces of information: Copy and save:

• Directory (tenant) ID: This is your Azure Tenant ID
• Application (client) ID: This is your Application (Client) ID

​

1.4 Generate a Client Secret

Navigate to Certificates & secrets in the left sidebar and click + New client secret. Add a description and choose an expiration period for your secret: After clicking Add, copy the Value immediately - this is your Client Secret.

​

1.5 Configure PowerBI API Permissions

Navigate to API permissions in the left sidebar and click + Add a permission.

1. Select PowerBI Service

2. Choose Delegated permissions
3. Select the following permissions:
   • Dataset.Read.All
   • Workspace.Read.All
   • Report.Read.All

4. Click Add permissions

​

1.6 Enable Service Principal Access in PowerBI Admin Portal (Admin Only)

Before service principals can access PowerBI workspaces, an administrator must enable this feature in the PowerBI admin portal.

​

Step 1: Navigate to Tenant Settings

Navigate to the PowerBI Admin Portal and you’ll see the Tenant settings page.

​

Step 2: Search for Developer Settings

In the upper-right corner, use the “Filter by keyword” search box to search for “developer” or “service principal” to quickly find the relevant setting.

​

Step 3: Locate and Enable Service Principal Access

Scroll through the filtered results or navigate to the “Developer settings” section. Look for the setting named:

• “Service principals can use Fabric APIs” (in newer versions), or
• “Service principals can use Power BI APIs” (in older versions)

​

Step 4: Configure the Setting

1. Click on the setting to expand it
2. Toggle the switch to Enabled
3. Choose the scope:
   • The entire organization: All service principals can access PowerBI APIs
   • Specific security groups: Only service principals from designated Azure AD security groups can access (recommended for tighter control)
4. If you chose specific security groups, click + Add and search for your security group
5. Click Apply at the bottom to save your changes

​

Step 2: PowerBI Workspace Configuration

After creating your Azure AD app registration and enabling service principal access, you need to add the service principal to your PowerBI workspace.

​

2.1 Navigate to Your PowerBI Workspace

Go to https://app.powerbi.com and sign in with your PowerBI account. Select the workspace you want to connect to TextQL.

​

2.2 Add Service Principal to Workspace

To grant your Azure AD application access to the workspace, you need to add it as a member.

1. In your PowerBI workspace, click the Manage access button in the top toolbar

2. In the “Manage access” dialog that appears, click + Add people or groups
3. In the search box, type the name of your Azure AD application (e.g., “TextQL PowerBI Connector”)

4. Select your application from the search results. It will be labeled as (Service Principal)
5. Assign an appropriate role:
   • Viewer: Read-only access to datasets and reports (minimum required for TextQL)
   • Contributor: Can generate embed tokens for viewing reports in TextQL
   • Member: Full access to APIs and content (recommended for full functionality)
   • Admin: Full access including workspace management
6. Click Add to grant access

​

Step 3: Creating the Connector in TextQL

Now that you have your Azure credentials and workspace configured, you can create the PowerBI connector in TextQL.

​

3.1 Navigate to the Connectors Page

Go to the TextQL Connectors Page and click the PowerBI card to add a new PowerBI connector.

​

3.2 Fill in the Connector Form

A form will appear asking for your PowerBI connection details: Enter the credentials you obtained from Azure:

• Connector Name: A descriptive name for this connector (e.g., “Marketing PowerBI Workspace”)
• Azure Tenant ID: The Directory (tenant) ID from your Azure app registration
• Application (Client) ID: The Application (client) ID from your Azure app registration
• Client Secret: The client secret value you generated earlier

​

3.3 Test and Create the Connector

Click Test Connection to verify your credentials are correct. If the test succeeds, you’ll see a green checkmark with the message “Connection test passed! You can now save the connector.” Click Create Connector to save your PowerBI connector.

​

Step 4: Syncing Your PowerBI Data

After creating your connector, TextQL will automatically navigate to the PowerBI Explorer and begin discovering your PowerBI content.

​

4.1 Automatic Discovery

When you click “Create Connector”, TextQL will:

1. Automatically navigate to the PowerBI Explorer page
2. Automatically start discovering reports and datasets from your PowerBI workspace

The discovery process will identify:

• Reports: All reports and dashboards in your PowerBI workspace
• Datasets: All datasets with their tables and relationships
• Workspaces: Multiple workspaces if your service principal has access to them

​

4.2 Select Content to Sync

After discovery completes, you can select which items to sync:

1. Use the search box to find specific reports or datasets
2. Switch between Reports and Datasets tabs
3. Filter by All, Synced, or Discovered items
4. Select specific workspaces from the dropdown
5. Click the + icon on individual items to select them
6. Or use “Select All Reports”/“Select All Datasets” to sync multiple items at once
7. Click “Sync X Items” to sync the selected content

​

4.3 Troubleshooting: Missing Data Previews

If you don’t see data previews or table metadata in the sync interface, this is likely due to PowerBI API access restrictions. This does not affect your ability to chat with Ana about your data.

​

Step 5: Chatting with Your PowerBI Data

Once your PowerBI connector is set up and synced, you can start chatting with your PowerBI data.

​

5.1 Start a New Chat

Navigate to TextQL Chat to begin asking questions about your PowerBI data.

​

5.2 Attach Your PowerBI Connector

In the chat interface, click the + icon and select Attach PowerBI. Choose the connector you just created. Then choose the datasets or reports you want to attach to the chat.

​

5.3 Ask Ana About Your Data

Ana can:

• Browse and query your PowerBI datasets directly
• Generate DAX queries against the underlying data
• Create visualizations and analyses
• Answer questions about your data structure and content

​

Troubleshooting

​

Connection Test Fails

If your connection test fails, check the following:

1. Verify Azure credentials: Ensure Tenant ID, Client ID, and Client Secret are correct
2. Check API permissions: Confirm your Azure AD app has the required PowerBI permissions
3. Verify workspace access: Ensure the service principal has been added to the PowerBI workspace
4. Check secret expiration: Client secrets expire - you may need to generate a new one
5. Review Azure AD policies: Some organizations have conditional access policies that may block service principal access

​

Cannot See Expected Datasets

If you’re connected but don’t see expected datasets:

1. Verify workspace permissions: The service principal needs at least Viewer access to the workspace
2. Check dataset permissions: Some datasets may have row-level security (RLS) that restricts access

​

Authentication Errors

If you encounter authentication errors while using the connector:

1. Client secret expiration: Generate a new client secret in Azure and update your connector
2. Token issues: Try disconnecting and reconnecting the connector
3. Permission changes: Verify that workspace permissions haven’t been modified

​

Next Steps

• Explore other connector types
• Learn about the Ontology to organize your PowerBI data
• Set up scheduled reports based on your PowerBI data