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)
toolboxAPI.utils.openInConnectionBrowser(url, connectionTarget?)
Open a URL in the external browser associated with the tool's active connection. When the connection has a browser profile configured (e.g. a specific Chrome or Edge profile), the URL is opened in that browser and profile so the user is already authenticated. Falls back to the system default browser when no profile is configured.
Only https: and http: URLs are allowed.
// Open a record in the browser using the primary connection's browser profile
await toolboxAPI.utils.openInConnectionBrowser(
'https://contoso.crm.dynamics.com/main.aspx?etn=account&id=guid-here&pagetype=entityrecord',
)
// Open a URL using the secondary connection's browser profile
await toolboxAPI.utils.openInConnectionBrowser(
'https://contoso-dev.crm.dynamics.com/main.aspx?pagetype=entitylist&etn=account',
'secondary',
)
Parameters:
url: string— The URL to open (must usehttps:orhttp:protocol)connectionTarget?: 'primary' | 'secondary'— Which connection's browser profile to use. Defaults to'primary'.
Returns: Promise<void>
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)
Invocation API
The Invocation API enables inter-tool communication — one tool can launch another, pass prefill data, and receive a return value when the callee finishes.
toolboxAPI.invocation.launchTool(targetToolId, prefillData?, options?)
Launch another installed tool from within your tool and optionally pass prefill data. Returns a Promise that resolves with the data the target tool sends back via returnData(), or null if the target tool closes without returning data.
// Tool A: launch an entity-picker tool and wait for the result
const result = await toolboxAPI.invocation.launchTool(
'@my-org/entity-picker',
{ entityName: 'account' },
)
if (result) {
console.log('Selected ID:', result.selectedId)
console.log('Selected name:', result.selectedName)
}
Parameters:
targetToolId: string— npm package name (toolId) of the tool to launchprefillData?: Record<string, unknown>— Data to pre-populate the target tool's stateoptions?: object— Optional connection overrides:{ primaryConnectionId?, secondaryConnectionId? }
Returns: Promise<unknown> — Data returned by the target tool, or null if it closes without returning data
toolboxAPI.invocation.getLaunchContext()
Read the prefill data passed by the tool that launched this tool. Returns null if this tool was not launched via an inter-tool invocation.
// Tool B: read the launch context on startup
const ctx = await toolboxAPI.invocation.getLaunchContext()
if (ctx) {
console.log('Launched with entity:', ctx.entityName)
// Pre-populate UI based on ctx...
}
Returns: Promise<Record<string, unknown> | null>
toolboxAPI.invocation.returnData(returnData)
Return data back to the tool that launched this tool. This resolves the Promise returned by the caller's launchTool() call. If this tool was not launched by another tool, the call is a no-op.
// Tool B: after the user makes a selection, return it to the caller
await toolboxAPI.invocation.returnData({
selectedId: 'guid-here',
selectedName: 'Contoso Ltd',
})
Parameters:
returnData: Record<string, unknown>— Data to pass back to the caller
Returns: Promise<void>
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.