ToolBox API
The ToolBox API provides access to platform features and utilities.
For complete TypeScript definitions, install the @pptb/types package: bash npm install --save-dev @pptb/types
Connections
Get information about the active Dataverse connection(s).
toolboxAPI.connections.getActiveConnection()
Returns the currently active connection or null if none is selected.
const connection = await toolboxAPI.connections.getActiveConnection()
if (connection) {
console.log('Connected to:', connection.name)
console.log('Environment:', connection.environment)
console.log('URL:', connection.url)
} else {
console.log('No active connection')
}
Returns: Promise<DataverseConnection | null>
interface DataverseConnection {
id: string // Unique identifier of the connection
name: string // Friendly name of the connection
url: string // Base URL of the Dataverse instance
environment: 'Dev' | 'Test' | 'UAT' | 'Production' // Environment classification
environmentColor?: string // Hex color code associated with the environment (added in 1.2.0)
category?: string // Category label assigned to the connection (added in 1.2.0)
categoryColor?: string // Hex color code for the category badge (added in 1.2.0)
createdAt: string // ISO date string of when the connection was created
lastUsedAt?: string // ISO date string of when the connection was last used
isActive?: boolean // @deprecated legacy field retained for backwards compatibility
}
Secondary Connections
As a tool developer, you may require access to a second Dataverse connections. This can be useful for copying data or configuration between environments.
To enable this feature, you must update the package.json file to indicate your tool requires multiconnections.
{
"name": "@toolname",
"version": "0.1.10",
"displayName": " My Awesome Tool",
"description": "A Power Platform Tool Box tool to do awesome things",
"main": "index.html",
"icon": "icons/test.svg",
"contributors": [
"Awesome Developer "
],
// Other properties...
// This section enables multiple connections
"features": {
"multiConnection": "required" or "optional",
"minAPI": "1.2.0"
},
Use top-level icon for your SVG icon path (relative to the dist root, for example icons/test.svg). To ensure the icon adapts to dark/light theme, set SVG fill to currentColor.
When the user opens your tool, they are presented with the option to connect to a primary and secondary environment.
toolboxAPI.connections.getSecondaryConnection()
Returns the currently active secondary connection or null if none is configured.
const secondaryConnection =
await toolboxAPI.connections.getSecondaryConnection()
if (secondaryConnection) {
console.log('Connected to:', secondaryConnection.name)
console.log('Environment:', secondaryConnection.environment)
console.log('URL:', secondaryConnection.url)
} else {
console.log('No active secondary connection')
}
Returns: Promise<DataverseConnection | null>
interface DataverseConnection {
id: string // Unique identifier of the connection
name: string // Friendly name of the connection
url: string // Base URL of the Dataverse instance
environment: 'Dev' | 'Test' | 'UAT' | 'Production' // Environment classification
environmentColor?: string // Hex color code associated with the environment (added in 1.2.0)
category?: string // Category label assigned to the connection (added in 1.2.0)
categoryColor?: string // Hex color code for the category badge (added in 1.2.0)
createdAt: string // ISO date string of when the connection was created
lastUsedAt?: string // ISO date string of when the connection was last used
isActive?: boolean // @deprecated legacy field retained for backwards compatibility
}
When interacting with dataverse and you want to use the secondary connection, pass the connectionTarget parameter as 'secondary'. ConnectionTarget is optional and defaults to 'primary'.
// Example usage of dataverseAPI using secondary connection
const myTables = await dataverseAPI.getAllEntitiesMetadata(
['logicalName'],
'secondary',
)
Utils
Utility functions for notifications, clipboard, and more.
Breaking Change: saveFile() and selectPath() have been migrated to the File System API. See File System API for details.
toolboxAPI.utils.showNotification(options)
Display a notification to the user.
await toolboxAPI.utils.showNotification({
title: 'Success',
body: 'Operation completed successfully',
type: 'success', // 'info' | 'success' | 'warning' | 'error'
duration: 3000, // Auto-dismiss after 3 seconds
})
Parameters:
options- Notification configuration object
Types:
type:'info' | 'success' | 'warning' | 'error'duration: Number in milliseconds (0 = persistent)
toolboxAPI.utils.copyToClipboard(text)
Copy text to the system clipboard.
const data = JSON.stringify({ accounts: [], contacts: [] }, null, 2)
await toolboxAPI.utils.copyToClipboard(data)
await toolboxAPI.utils.showNotification({
title: 'Copied',
body: 'Data copied to clipboard',
type: 'success',
})
toolboxAPI.utils.getCurrentTheme()
Get the current application theme.
const theme = await toolboxAPI.utils.getCurrentTheme()
document.body.classList.add(`theme-${theme}`)
Returns: Promise<'light' | 'dark'>
toolboxAPI.utils.showLoading(message) / hideLoading()
Show/hide a loading overlay.
await toolboxAPI.utils.showLoading('Fetching data from Dataverse...')
try {
// Perform long-running operations
const data = await fetchLargeDataset()
processData(data)
await toolboxAPI.utils.showNotification({
title: 'Success',
body: 'Data processed successfully',
type: 'success',
})
} finally {
await toolboxAPI.utils.hideLoading()
}
toolboxAPI.utils.executeParallel(...promises)
Execute multiple async operations in parallel.
const [account, contact, opportunities] =
await toolboxAPI.utils.executeParallel(
dataverseAPI.retrieve('account', accountId, ['name']),
dataverseAPI.retrieve('contact', contactId, ['fullname']),
dataverseAPI.fetchXmlQuery(opportunityFetchXml),
)
console.log('All data fetched:', account, contact, opportunities)
Terminal
Create and manage terminal sessions (context-aware to your tool).
toolboxAPI.terminal.create(options)
Create a new terminal.
const terminal = await toolboxAPI.terminal.create({
name: 'Build Terminal',
cwd: '/path/to/project',
env: {
NODE_ENV: 'production',
},
})
console.log('Terminal created:', terminal.id)
toolboxAPI.terminal.execute(terminalId, command)
Execute a command in a terminal.
const result = await toolboxAPI.terminal.execute(terminal.id, 'npm install')
if (result.exitCode === 0) {
console.log('Command completed successfully')
} else {
console.error('Command failed:', result.error)
}
toolboxAPI.terminal.setVisibility(terminalId, visible)
Show or hide a terminal's UI panel.
await toolboxAPI.terminal.setVisibility(terminal.id, true)
toolboxAPI.terminal.list()
List all terminals created by your tool.
const terminals = await toolboxAPI.terminal.list()
console.log(`This tool has ${terminals.length} terminals`)
toolboxAPI.terminal.close(terminalId)
Close a terminal.
await toolboxAPI.terminal.close(terminal.id)
Tool Context
toolboxAPI.getToolContext()
Returns the current tool context used by the framework.
const context = await toolboxAPI.getToolContext()
console.log('Tool ID:', context.toolId)
console.log('Instance ID:', context.instanceId)
console.log('Primary URL:', context.connectionUrl)
console.log('Secondary URL:', context.secondaryConnectionUrl)
Returns: Promise<ToolContext>
interface ToolContext {
toolId: string | null
instanceId?: string | null
connectionUrl: string | null
connectionId?: string | null
secondaryConnectionUrl?: string | null
secondaryConnectionId?: string | null
}
ToolContext intentionally does not contain access tokens. Use dataverseAPI for authenticated Dataverse operations.