• Public
  • Public/Protected
  • All

Trimble Connect 3D Viewer - Workspace API

Workspace API Documentation

The Workspace API of Trimble Connect 3D Viewer allows the client applications to interact with the 3D Viewer. It utilizes window.postMessage() to facilitate the communication. There are two methods to utilize the Workspace API:

  • The client application embeds the 3D Viewer in an iframe.
  • The client application is embedded inside the 3D Viewer as a side panel.


Trimble Connect 3D Viewer allows authentication using GET parameter accessToken and refreshToken. If the accessToken is not specified, the authentication is done through the usual login page in the 3D Viewer application.

Quick Start

  1. Add the component as a dependency to your project:

    npm i workspace-api --save

For ES6-module-friendly consumers, you can import the modules directly, or import them from the root module. It is also possible to directly import the IIFE module from the URL of the 3D Viewer application.

<script src="https://3d.connect.trimble.com/trimbleconnect.workspace.api.js" />

  1. Put together the 3D Viewer and the client application:

    Page structure

    • Embed the 3D Viewer inside the application using an iframe

        sandbox="allow-scripts allow-modals allow-forms allow-same-origin"
        height="700px" />
    • Embed the application inside the 3D Viewer

      Pass the (comma-separated) URL(s) of the client application(s) via a GET parameter to the 3D Viewer. The client applications will be displayed as a tab page on the left side panel. The following parameters are supported:

      • pluginmanifest: A comma-separated list of client application manifests. The data structure of the manifest file should be the JSON representation of the ExtensionSetting interface
      • plugin: A comma-separated list of client application URLs. Each plugin URL will be embedded in an iframe, which is displayed in a separate tab page
      • pluginicon: A comma-separated list of icon URLs (which will be used as the icon for the plugin tab page)
      • plugintitle: A comma-separated list of plugin titles (which will be used as the tooltip for the tab page)

      Each plugin tab page will use the icon and title with the same index. Thus, if pluginicon and/or plugintitle is defined, the number of the comma-separated parameters must equal to the number of the comma-separated plugin URLs defined in plugin parameter. For instance:


      • Plugin with URL plugin1Url will have the icon1Url and title title1
      • Plugin with URL plugin2Url will have the icon2Url and title title2
  2. Initiates the connection between the client application and 3D Viewer

    • Embed the 3D Viewer inside the application using an iframe: This should be done after the iframe has been loaded. The connection initiation should be done in an async function as the connection is only established once the user has selected a Trimble Connect project in the 3D Viewer.

      viewer.onload = async function () {
      var API = await Workspace.connect(viewer, (event, data) => {
          console.log("Event: ", event, data);
      • In order to automatically select certain project/model after Trimble Connect 3D Viewer application has started, the model ID (and model ID) could be passed as parameters in the URL
        • https://<3D Viewer URL>/?projectId=MyProjectId

        • https://<3D Viewer URL>/?projectId=MyProjectId&modelId=ModelId1,ModelId2

    • Embed the application inside the 3D Viewer: Directly issue the connect request to the parent window (3D Viewer) that is hosting the application:

      var API = await Workspace.connect(window.parent, (event, data) => {
          console.log("Event: ", event, data);
  1. All the APIs will be exposed through the return value of connect method.

The workflow of the Workspace API can be illustrated as below:

Workspace API Workflow

Usage with TypeScript

The Trimble Connect 3D Viewer - Workspace API bundles TypeScript v2 definition files for use in TypeScript projects and to support tools that can read .d.ts files.


Check out the example client application for more details!

Configuration from 3D Viewer

It is possible to configure plugins that are used for each Connect Project via 3D Viewer Extensions Settings. Basically, it is possible to define a new plugin manually or through an extension definition (a manifest)

  • Manually: Specify all plugin parameters manually
    • Click on Advanced text button
    • Specify the Plugin title, Plugin URL (and other plugin metadata)
  • Extension URL: The URL to the extension manifest file, which is a JSON file that specifies all plugin parameters (e.g. Plugin title, Plugin URL...). The data structure follows the PluginSetting interface. For example:
          "pluginUrl": "https://my.awesome.app/plugin",
          "title": "This is my plugin",
          "infoUrl": "https://my.awesome.app/plugin/help.html"