Power Platform Tool Box

Tool Development Guide

Power Platform Tool Box provides a secure, extensible platform for creating custom tools as web applications. This guide will help you build, test, and publish your own tools.

Overview

Tools are web applications that run in isolated environments and communicate with the ToolBox through secure APIs:

  • Webview-Based: Each tool runs in a sandboxed iframe with limited API access
  • Organized APIs: Namespaced APIs for connections, utilities, terminals, events, and Dataverse
  • Secure Communication: Structured message protocol via postMessage
  • Context-Aware: Tool ID and connection context automatically managed
  • Type-Safe: Full TypeScript support with @pptb/types package

API Architecture

Tools have access to two main APIs:

ToolBox API (window.toolboxAPI)

Organized into namespaces:

  • connections - Get active Dataverse connection (read-only)
  • utils - Notifications, clipboard, file operations, theme
  • settings - Tool-specific settings storage (context-aware)
  • terminal - Create and manage terminals (context-aware)
  • events - Subscribe to platform events (tool-specific)

Dataverse API (window.dataverseAPI)

Complete HTTP client for Dataverse:

  • CRUD operations (create, retrieve, update, delete)
  • FetchXML queries
  • Metadata operations
  • Execute actions and functions

Quick Start

Prerequisites (Optional)

Install Yeoman and the PPTB generator globally:

npm install -g yo generator-pptb

Or use npx without global installation:

npx --package yo --package generator-pptb -- yo pptb

Create Your Tool Package

yo pptb
# or
yo pptb my-tool

Follow the prompts to generate your tool structure:

my-tool/
├── package.json
├── index.html
├── styles.css
├── app.ts
└── README.md

Define package.json

{
  "name": "@powerplatform/my-tool",
  "version": "1.0.0",
  "displayName": "My Tool",
  "description": "Description of what your tool does",
  "author": "Your Name",
  "keywords": ["powerplatform", "dataverse", "toolbox"]
}

Install Type Definitions

npm install --save-dev @pptb/types

Implement Your Tool

index.html:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Tool</title>
  <link rel="stylesheet" href="styles.css">
</head>
<body>
  <div id="app">
    <h1>My Power Platform Tool</h1>
    <div id="connection-info"></div>
    <button id="test-btn">Test API</button>
    <div id="output"></div>
  </div>
  <script src="app.js"></script>
</body>
</html>

app.ts:

/// <reference types="@pptb/types" />

async function initialize() {
  try {
    // Get active connection
    const connection = await toolboxAPI.connections.getActiveConnection();
    
    if (connection) {
      document.getElementById('connection-info')!.textContent = 
        `Connected to: ${connection.name} (${connection.environment})`;
    }
    
    // Subscribe to events
    toolboxAPI.events.on((event, payload) => {
      console.log('Event received:', payload.event, payload.data);
      
      if (payload.event === 'connection:updated') {
        initialize();
      }
    });
    
    // Show notification
    await toolboxAPI.utils.showNotification({
      title: 'Tool Loaded',
      body: 'My tool is ready!',
      type: 'success',
      duration: 3000
    });
  } catch (error) {
    console.error('Initialization error:', error);
  }
}

// Initialize when DOM is ready
if (document.readyState === 'loading') {
  document.addEventListener('DOMContentLoaded', initialize);
} else {
  initialize();
}

Testing Your Tool

Local Development

  1. Build your tool:

    npm run build

  2. Start watch mode (optional but recommended):

    npm run build -- --watch

  3. Enable Debug Menu:

    • Open Power Platform Tool Box
    • Go to Settings
    • Select the Show Debug Menu option
    • Click Save

  4. Load in ToolBox:

    • Navigate to Debug section (now visible in the sidebar)
    • Click Browse in "Load Local Tool"
    • Select your tool's root directory
    • Click Load Tool

  5. Test and iterate:

    • Make changes to your source files
    • Close the tool tab in ToolBox
    • Reopen from sidebar to see changes

Publishing Your Tool

1. Build your tool

npm run build

2. Prepare for Publishing

Ensure your package.json has all required fields:

{
  "name": "@org-name/my-tool",
  "version": "1.0.0",
  "displayName": "My Tool",
  "description": "Clear description of what your tool does",
  "main": "index.html",
  "author": "Your Name",
  "keywords": ["powerplatform", "dataverse", "toolbox"],
  "repository": {
    "type": "git",
    "url": "https://github.com/yourusername/your-tool"
  },
  "license": "MIT"
}

3. Finalize package for publishing

npm run finalize-package

4. Publish to npm

npm login
npm publish --access public

5. Submit to ToolBox Registry

Visit the Tool Submission Form and provide:

  • npm package name
  • Display name
  • Description
  • GitHub repository URL
  • Tags/categories

Next Steps

API ReferenceView Examples

Resources

Was this page helpful?