Trimble Connect Workspace API

Common errors

• TypeError: Cannot read properties of undefined (reading 'getProject')

  cause The `WorkspaceAPI.connect` method likely failed to return a valid API instance, or the promise from `connect` was not awaited, resulting in `api` being undefined or null when attempting to access its properties (e.g., `api.project`). This can happen if the connection times out or fails to establish.
  fix Ensure `await WorkspaceAPI.connect(...)` is used within an `async` function. Check the console for connection errors or timeouts. Verify the target window (`window.parent` for extensions, `iframe.contentWindow` for embedded viewers) is accessible and ready, and that the Trimble Connect application is loaded and listening. Increase the timeout if necessary.

• Uncaught DOMException: Blocked a frame from accessing a cross-origin frame.

  cause This browser security error occurs when JavaScript attempts to access properties of an `<iframe>`'s `contentWindow` or `contentDocument` that is hosted on a different origin, and the parent frame's origin is not permitted by the `iframe`'s `Access-Control-Allow-Origin` headers, or vice-versa. This specifically impacts direct DOM access, not necessarily `postMessage` itself if handled correctly.
  fix Ensure that the Trimble Connect Workspace API is initialized correctly via `WorkspaceAPI.connect()` with the appropriate target window, as it handles the cross-origin `postMessage` communication securely. Avoid direct JavaScript access to `iframe.contentWindow` properties (e.g., `iframe.contentWindow.document`) if the origins differ. Verify that if you are embedding a Trimble Connect component, the `iframe` itself is correctly configured and the host application is properly allowing cross-origin communication as per Trimble's guidelines.

• API Error: Manifest file URL is not CORS enabled.

  cause When registering an extension in Trimble Connect, the platform attempts to fetch the extension's `manifest.json` file. If the server hosting this manifest does not include the necessary `Access-Control-Allow-Origin` HTTP headers, the browser will block the request, preventing the extension from being loaded.
  fix Configure your web server to include `Access-Control-Allow-Origin` headers for your `manifest.json` file. For development, `Access-Control-Allow-Origin: *` can be used. For production, specify `web.connect.trimble.com` (and other relevant Trimble Connect domains) as the allowed origin.

Warnings

• breaking The `trimble-connect-project-workspace-api` package was deprecated. All integrations were required to migrate to `trimble-connect-workspace-api` by the end of Q1 2023. Older APIs ceased to function after this deadline.
  Fix: Migrate all existing integrations from `trimble-connect-project-workspace-api` to `trimble-connect-workspace-api`. Ensure your `package.json` reflects the correct dependency and update import statements and API calls according to the new API's documentation.
• gotcha When developing Trimble Connect extensions or embedding components, the URL hosting the extension's manifest file (e.g., `manifest.json`) must be CORS-enabled to allow access from Trimble Connect for Browser. Failure to set proper CORS headers will prevent the extension from being created or loaded.
  Fix: Configure your server to respond with appropriate CORS headers (`Access-Control-Allow-Origin`, `Access-Control-Allow-Methods`, etc.) for the manifest file URL. For development, `Access-Control-Allow-Origin: *` might suffice, but for production, restrict `Access-Control-Allow-Origin` to `web.connect.trimble.com` or other official Trimble Connect domains.
• gotcha The API relies on `window.postMessage()` for communication. While the library handles much of the complexity, developers must understand the security implications, especially related to `targetOrigin`. Though the library abstracts it, ensuring messages are only sent to and received from trusted origins is crucial for security. Improper configuration or direct `postMessage` usage can lead to cross-site scripting (XSS) or data leakage vulnerabilities.
  Fix: Always use the provided `WorkspaceAPI.connect()` method and its returned instance for all communications. Avoid direct `window.postMessage()` calls unless absolutely necessary and ensure robust origin validation if custom `postMessage` handling is implemented. Review Trimble Connect's security guidelines for extensions.
• breaking The domain for the Trimble Connect Web 3D Viewer changed from `3d.connect.trimble.com` to `web.connect.trimble.com`. Bookmarked 3D Viewer URLs might require updating.
  Fix: Update any hardcoded URLs or bookmarks pointing to the old 3D Viewer domain (`3d.connect.trimble.com`) to use the new domain (`web.connect.trimble.com`). While the old domain continued to work for a transitional period, it is no longer supported.

Install

• npm install trimble-connect-workspace-api npm
• yarn add trimble-connect-workspace-api yarn
• pnpm add trimble-connect-workspace-api pnpm

Imports

• connect
  wrong:

  import { connect } from 'trimble-connect-workspace-api';

  correct:

  import * as WorkspaceAPI from 'trimble-connect-workspace-api';
  const api = await WorkspaceAPI.connect(window.parent);

  The primary entry point is the `connect` static method, often imported as a namespace (`* as WorkspaceAPI`) to access all API methods.
• WorkspaceAPI

  import { WorkspaceAPI } from 'trimble-connect-workspace-api';

  While `connect` is the main method to *get* an API instance, the `WorkspaceAPI` type itself can be imported for type annotations. The `connect` method returns an instance that implements this interface.
• ExtensionAPI

  import { ExtensionAPI } from 'trimble-connect-workspace-api';

  Specific sub-APIs like `ExtensionAPI` can be imported for type hinting or direct access if deeply nested. It is usually accessed via the connected `WorkspaceAPI` instance (e.g., `api.extension`).

Quickstart

Demonstrates connecting to the Trimble Connect Workspace API as an extension, retrieving project details, setting a UI status message, and dynamically updating the extension's menu. It includes basic error handling and event listening.

import * as WorkspaceAPI from 'trimble-connect-workspace-api';

interface ProjectInfo {
  projectId: string;
  projectName: string;
}

// This example assumes the client application is embedded as an extension
// within the Trimble Connect environment, communicating with its parent window.
// If embedding the Trimble Connect Viewer/Modules, `window.parent` would be replaced
// with the `contentWindow` of the iframe.

async function initializeTrimbleConnectExtension() {
  try {
    console.log('Attempting to connect to Trimble Connect Workspace API...');
    const api = await WorkspaceAPI.connect(
      window.parent, // Target origin is handled internally; window.parent is typically used for extensions
      (eventName: string, data: any) => {
        console.log(`Received event: ${eventName}`, data);
        // Handle various events from the Trimble Connect environment
        if (eventName === 'extension.accessToken') {
          console.log('Access token received:', data.data); // data.data contains the actual token
        }
      },
      30000 // Connection timeout in milliseconds
    );

    console.log('Successfully connected to Workspace API.');

    // Example: Get current project information
    const project: ProjectInfo = await api.project.getProject();
    console.log('Current project:', project.projectName, `(ID: ${project.projectId})`);

    // Example: Set a status message in the Trimble Connect UI
    api.extension.setStatusMessage(`Extension loaded for project: ${project.projectName}`);

    // Example: Update the UI menu (assuming this is an extension)
    api.ui.setMenu({
      id: 'my-extension-menu',
      title: 'My Custom Extension',
      icon: 'https://example.com/menu-icon.png',
      command: 'open-my-extension',
      children: [
        { id: 'sub-menu-1', title: 'Action 1', command: 'action-1-clicked' },
        { id: 'sub-menu-2', title: 'Action 2', command: 'action-2-clicked' }
      ]
    });

  } catch (error) {
    console.error('Failed to connect or use Workspace API:', error);
    if (error instanceof Error && error.message.includes('timeout')) {
        console.error('Connection timed out. Ensure the host application is ready and accessible.');
    }
  }
}

initializeTrimbleConnectExtension();