> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.cxplanner.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Integrate CxPlanner with Power BI using the Custom Connector

## Overview: Power BI custom connector

The CxPlanner Power BI connector loads project data such as tasks, checklists, assets, and certificates into Power BI Desktop through the CxPlanner API, which is used when you need custom dashboards and analytics outside CxPlanner.

* Your role must be **Company Admin**, and you need a valid API key.
* You can find the connector in Power BI Desktop - **Get Data** - **Other** - **CxPlanner Connector**.
* This reads project data into Power BI. It does not change CxPlanner data.

|| Only users with the **Company Admin** role and a valid API key can install and configure the connector.

## What CxPlanner does through the Power BI connector

* Fetches data through the CxPlanner API
* Flattens nested JSON for report building
* Paginates large results automatically (about 1000 records per chunk)
* Supports module filters and optional query parameters
* Respects CxPlanner access controls for the API key

## How to connect Power BI to CxPlanner

### Prepare your environment
1. Install the latest **Power BI Desktop**.
2. Generate or request your [CxPlanner API key](https://help.cxplanner.com/en-us/article/set-up-api-access-sljl5q/).

### Install the connector
1. Download the `Connector.pq` file.
2. Move it to `%USERPROFILE%\Documents\Power BI Desktop\Custom Connectors\`.
3. Create that folder if it does not exist.
4. Open Power BI Desktop.
5. Go to **File** - **Options and settings** - **Options** - **Security** - **Data Extensions**.
6. Select allow any extension to load without validation or warning.
7. Restart Power BI Desktop.

### Connect to CxPlanner
1. Open **Get Data** - **More** - **Other** - **CxPlanner Connector**.
2. Enter **Base URL**: `https://app.cxplanner.com`.
3. Enter **Project ID** (for example `12345`).
4. Enter your **API Key**.
5. Optionally set **Module** (for example `qa`, `assets`, `sitevisit`).
6. Choose the tables to load from the navigator.

## Results: Power BI connector data

### Supported modules and endpoints

| Category | Available endpoints |
|---|---|
| Project management | Projects, Project Details, Tasks, Users |
| Quality assurance | QA Checklists, Checklist Items, Files |
| Assets | Items, Types, Fields, Certificates |
| Templates | Checklist Templates, Template Items |
| File management | Files, Folders, Approval Statuses |
| Company data | Company Users, User Details |

### Supported module parameter values

* `systemtestview` (default)
* `qa`
* `qc`
* `assets`
* `sitevisit`

### Required and optional parameters

| Parameter | Required | Description |
|---|---|---|
| Base URL | Yes | https://app.cxplanner.com |
| Project ID | Yes | Project identifier |
| API Key | Yes | API authentication key |
| Module | No | Filter by module |
| Status | No | Comma-separated status codes |
| User Email | No | Limit results to one user |
| Checklist Name | No | Filter by checklist title |

Optional advanced IDs include Checklist Template UUID, Asset UUID / Item UUID, Certificate UUID, Task ID, and Folder Key or File Hash.

### Suggested table relationships

| Table A | Table B | Join field |
|---|---|---|
| Projects | Tasks | Project ID |
| Tasks | Users | User UUID / Email |
| Assets | Certificates | Asset UUID |
| Checklists | Templates | Template UUID |

### Example report setups

* Project dashboard: load Project Tasks and Project Users
* QA reporting: set Module to `qa`, then load Checklists List and Checklist Items
* Asset compliance: load Assets Items, Types, and Certificates, then join on Asset UUID

| Action | Required role |
|---|---|
| Install connector | Company Admin |
| Generate API key | Company Admin |
| View project data | Project Admin or higher |
| Access asset data | Project Manager or higher |

## Troubleshooting: Power BI connector

| Problem | Cause | Solution |
|---|---|---|
| Invalid API Key error | Incorrect or expired API key | Verify the key in CxPlanner, regenerate if needed, then reconnect in Power BI |
| Data returns empty | Wrong Project ID, or API user lacks project access | Confirm Project ID and add the API user to the project if the key is scoped |
| Slow loading | Large dataset without filters | Add Module or other filters, or use incremental refresh |
| Checklist data missing | Wrong Module parameter | Set Module to `qa` (or the module that holds your checklists) and reload |
| Connector not listed | Connector.pq not installed or extensions blocked | Confirm the Custom Connectors path, allow extensions under Security, then restart Power BI Desktop |

When reporting issues, include Power BI version, connector version, the error message, steps to reproduce, and Project ID if possible.