Guides and Articles

Use this documentation when building your Trimble Connect apps

Get started with Workflow tools (status sharing) API

Updated: 30 Jul 2019

Trimble Connect Workflow tools

Trimble Connect Workflow tools API

Trimble Connect Workflow tools enable cloud-based BIM supply chain management. You can control and keep track of assembly and object level status information for project management, scheduling and design review purposes.

Download Workflow tools for Trimble Connect desktop

Usage of Trimble Connect Workflow tools API

External systems are able to integrate with the Trimble Connect using the server side Core APIs and Workflow Tools (status sharing) API. For example, fabrication ERP systems can publish the status data real time using the status sharing API.

If you are a fabricator or equivalent, most probably you have an ERP system or other system with a status concept in place. With the status sharing API, you can visualize your production status on BIM with a “live feed” and update your system status from the Trimble Connect user interfaces.

RESTful API

The Trimble Connect Workflow tools API is a standard RESTful API. It uses GET to retrieve information, PUT to store or update a resource, POST to create a new entity, and DELETE to remove it.

Access tokens are region specific

With the Workflow tools API all requests including the access_token exchange are done against the region specific servers in the same regions as core Trimble Connect. The access_tokens are region specific, as there is no master region.

Accessing the Workflow tools API

You can get the region specific server URLs by adding the Trimble Connect region name to the beginning of the base URL:

API Base URL
Europe    https://europe.tcstatus.tekla.com
US
https://northamerica.tcstatus.tekla.com
Asia
https://asia.tcstatus.tekla.com

Status values

Status actions are set up per project to match your process.

Possible status values are: 

  • None
  • Enable
  • Commit
  • Started
  • Paused
  • Completed

Allowed status values can be configured per status action.

Code examples

Authenticate using Oauth2 (Password grant type)

Trimble Identity token is returned in the response body as id_token.

POST https://identity.trimble.com/i/oauth2/token
?grant_type=password&username=<username>&password=<password>
&client_id=<client_id>&client_secret=<client_secret>
&scope=openid&tenantDomain=trimble.com
Content-Type: application/x-www-form-urlencoded

 

Exchange the id_token for a Workflow tools API access token (from European server)

The status_token is returned in the response

POST https://europe.tcstatus.tekla.com/statusapi/1.0/auth/token
Authorization: Bearer <id_token>

 

The Workflow tools API can then by invoked using the status_token

  1. Query Status Actions in a project: 
    GET https://europe.tcstatus.tekla.com/statusapi/1.0/projects/<project_id>/statusactions
    Authorization: Bearer <status_token>

     

  2. Get current statuses for an action: 
    GET https://europe.tcstatus.tekla.com/statusapi/1.0/projects/<project_id>/status
    ?statusActionId=<action_id>
    Authorization: Bearer <status_token>

     

  3. Add a Status Action: 
     POST https://europe.tcstatus.tekla.com/statusapi/1.0/projects/<project_id>/statusactions
    Authorization: Bearer <status_token>
    Content-Type: application/json
    {
           "isPublic": true,
           "name": "Test action",
           "allowedValues": "None,Started,Paused,Completed"
    
    }

     

  4. Add Status Events for two objects.
    POST https://europe.tcstatus.tekla.com/statusapi/1.0/projects/<project_id>/statusevents
    Authorization: Bearer <status_token>
    Content-Type: application/json
    [{
           "objectId": "ifc-guid1",
           "statusActionId": "<action_id>",
           "value": "Completed",
           "valueDate": "2017-06-01T19:54:30.00Z"
    },
    {
           "objectId": "ifc-guid2",
           "statusActionId": "<action_id>",
           "value": "Paused",
           "valueDate": "2017-06-02T16:30:00.00Z"
    }]

    Note: Object guids must be in the IFC GUID format.