CxPlanner Power BI Custom Connector

A comprehensive Power BI custom connector for integrating CxPlanner project management data into your Power BI reports and dashboards.

Overview

The CxPlanner Connector enables seamless integration between CxPlanner's project management platform and Power BI, allowing you to:

• Import project data, tasks, and user information
• Access checklists, assets, and quality assurance data
• Retrieve certificates, templates, and file information
• Build comprehensive project management dashboards

Features

Core Data Sources

• Project Management: Projects list, project details, tasks, and users
• Quality Assurance: QA checklists, checklist items, and files
• Assets Management: Asset items, types, fields, certificates, and views
• Templates: Checklist templates and template items
• File Management: Folders, files, and approval statuses
• Company Data: Company users and user details

Key Capabilities

• Automatic Pagination: Handles large datasets automatically
• Dynamic Module Support: Supports multiple modules (systemtestview, assets, qa, qc, sitevisit)
• Conditional Endpoints: Smart loading of relevant data based on provided parameters
• Complete Data Flattening: Automatically expands nested JSON structures
• Flexible Filtering: Filter data by status, user, or checklist name

Installation

Prerequisites

• Power BI Desktop (latest version recommended)
• CxPlanner API access with valid API key
• Administrator rights to install custom connectors

Installation Steps

1. Download the Connector

• Save the Connector.pq file to your local machine

2. Install in Power BI Desktop

• Copy the .pq file to your Power BI custom connectors folder:

     %USERPROFILE%\Documents\Power BI Desktop\Custom Connectors\

• If the folder doesn't exist, create it manually

3. Enable Custom Connectors

• Open Power BI Desktop
• Go to File → Options and settings → Options
• Navigate to Security → Data Extensions
• Select "Allow any extension to load without validation or warning"
• Restart Power BI Desktop

Configuration

Required Parameters

Optional Parameters

Advanced Parameters

For specific data retrieval, you can provide these UUIDs and identifiers:

• Asset UUID: For specific asset data
• Asset Item ID/UUID: For asset item details
• Certificate UUID: For certificate information
• Package UUID: For package data
• Checklist Template UUID: For template details
• User UUID: For user-specific information
• Folder Key/Name: For file and folder data
• Task ID: For specific task information
• File Hash: For file URL retrieval

Usage

Basic Setup

1. Open Power BI Desktop
2. Get Data → More → Other → CxPlanner Connector
3. Enter Connection Details:

• Base URL: Your CxPlanner API endpoint
• Project ID: Your project identifier
• Module: Choose from available modules or leave default

4. Authenticate: Enter your API key when prompted
5. Select Data: Choose from available endpoints in the navigator

Available Data Endpoints

Core Project Data

• Global Projects List: All accessible projects
• Project Details: Detailed project information
• Project Users: Users associated with the project
• Project Tasks: All project tasks with pagination
• Dashboard Tasks: Dashboard task summary

Quality Management

• Checklists List: Project checklists by module
• Checklists Flat List: Flattened checklist structure
• QA Checklist: Specific checklist details (requires Checklist ID)
• QA Checklist Items: Individual checklist items
• QA Checklist Files: Files associated with checklists

Asset Management

• Assets Items: All project assets with pagination
• Assets Types: Asset type definitions
• Assets Fields: Asset field configurations
• Assets Certificates: Asset certificates with pagination
• Assets Views: Asset view configurations

Templates & Company

• Checklist Templates: Available checklist templates
• Company Users: Company user directory
• Template Items: Specific template details

File Management

• Folders List: Project folder structure
• Files in Folder: Files within specific folders
• Files Approval Status: File approval workflows
• File URLs: Direct file access links

Example Use Cases

Project Dashboard Creation

1. Connect to CxPlanner with your project ID
2. Load "Project Tasks" and "Project Users" tables
3. Create relationships between tasks and users
4. Build visualizations showing task progress and assignments

Quality Assurance Reporting

1. Set module to "qa" 
2. Load "Checklists List" and "QA Checklist Items"
3. Analyze checklist completion rates
4. Track quality metrics across different asset types

Asset Management Analytics

1. Load "Assets Items" and "Assets Types"
2. Connect "Assets Certificates" for compliance tracking
3. Create asset lifecycle and certification status reports

Data Model Recommendations

Establishing Relationships

• Projects ↔ Tasks: Use Project ID
• Tasks ↔ Users: Use User UUID/Email
• Assets ↔ Certificates: Use Asset UUID
• Checklists ↔ Templates: Use Template UUID

Performance Optimization

• Incremental Refresh: Configure for large datasets
• Query Folding: Utilize filtered endpoints when possible
• Selective Loading: Only load required endpoints
• Scheduled Refresh: Set up automatic data updates

Troubleshooting

Common Issues

Authentication Errors

• Issue: "Invalid API Key" error
• Solution: Verify API key is correct and has proper permissions
• Check: Ensure API key hasn't expired

Connection Timeouts

• Issue: Requests timing out
• Solution: Check network connectivity to CxPlanner servers
• Alternative: Try reducing data scope with specific parameters

Empty Data Returns

• Issue: Tables loading but showing no data
• Solution: Verify Project ID exists and is accessible
• Check: Confirm user permissions for requested data

Module-Specific Data Missing

• Issue: Expected checklist data not appearing
• Solution: Verify correct module parameter (qa, qc, assets, etc.)
• Check: Confirm module contains data in CxPlanner

Performance Issues

Large Dataset Handling

• Use specific UUIDs to limit data scope
• Leverage the built-in pagination for large tables
• Consider incremental refresh for frequently updated data

Memory Usage

• Close unnecessary queries in Power Query Editor
• Limit simultaneous endpoint loading
• Use query folding where possible

API Rate Limits

The connector respects CxPlanner API rate limits:

• Pagination: Automatically handles large datasets in 1000-record chunks
• Request Throttling: Built-in handling for API rate limiting
• Error Handling: Graceful handling of temporary API unavailability

Security Considerations

• API Key Storage: Keys are stored securely by Power BI
• Data Transmission: All API calls use HTTPS encryption
• Access Control: Respects CxPlanner user permissions
• Credential Management: Use Power BI's credential manager

Support and Updates

Getting Help

1. Check Documentation: Review this README and Power BI documentation
2. API Documentation: Refer to CxPlanner API documentation
3. Community Support: Power BI community forums
4. Technical Support: Contact your CxPlanner administrator

Version History

• v1.0.0: Initial release with core functionality
• Base project data endpoints
• Quality assurance integration
• Asset management support
• Automatic pagination and data flattening

Reporting Issues

When reporting issues, please include:

• Power BI Desktop version
• Connector version
• Error messages (screenshots helpful)
• Steps to reproduce the issue
• Sample project ID (if possible)

Advanced Configuration

Custom Modules

The connector supports these modules:

• systemtestview (default)
• assets
• qa (Quality Assurance)
• qc (Quality Control)
• sitevisit

Query Optimization

• Use specific parameters to reduce data scope
• Implement incremental refresh for large datasets
• Create composite models for complex scenarios

Integration Patterns

• Star Schema: Center around Projects table
• Snowflake: Detailed normalization for complex reporting
• Flat Tables: For simple dashboards and quick analysis

License and Compliance

This connector is designed to work with CxPlanner's existing API terms of service. Ensure compliance with:

• CxPlanner API usage policies
• Your organization's data governance requirements
• Power BI licensing terms

For additional support or questions about this connector, please contact your CxPlanner system administrator or Power BI support team.

Updated on: 07/28/2025