Public API v1.0 Documentation
Draft: October 22, 2014 Contents Introduction
APIs in Trimble Connect allows one to read, write and update data into/out of the Connect platform. Now, one can create folders, upload/download files, modify views and do much more from within an application using Trimble Connect’s powerful API.
This document has two sections: A. Public Server APIs (Token based) B. Public 3D Viewer APIs (Token based)
Section A Public Server APIs are token based REST APIs that can be used from any client and can be exposed to the outside world or be used for systems integration/Apps etc.
Section B Public Viewer APIs are token based JavaScript APIs can be used to manipulate the viewer which can be embedded into any other web based application.
How to get your API Key
API key is used to generate access token to access all the Trimble Connect APIs. This key is based on your account email and does not change or expire. To generate this key you must first sign in to Trimble Connect. Another option for authentication is to use cookie based sync login API rather than logging in directly to Trimble Connect.
Use your credentials or signup for a new account: https://app.prod.gteam.com/gteam/app
After signing in, copy this URL in the same browser address bar you signed in and get your API Key
URL
GET https://app.prod.gteam.com/gteam/app/useraccounts/me/apikey
EXAMPLE RESPONSE
1. { 2. "key": "lpv5XiiJnD1XaCPvFW1QIU4tZFd1akpOUVhBOlFRckxtsk9qUm9Z" 3. }
Date format The date value used in the APIs is expressed as Unix epoch timestamp. All dates are in UTC.
EXAMPLE: 1410412870000
Authentication To use the public APIs, you will need to add the “Authorization” header to your requests.
Authorization Bearer access_token
Replace “access_token” with the value you get from the /auth API request explained below
POD Specific domain urls
Use the “origin” field value from the /regions API to determine the host URL for the API calls for specific POD of the project.
Exceptions
The APIs return JSON responses for most of the APIs on success. In case of exceptions, a JSON object is returned with error code and a message with HTTP status 409.
EXAMPLE RESPONSE
HTTP 409 Conflict
1. { 2. "message": "INVALID_SESSION", 3. "errorcode": "INVALID_SESSION" 4. }
Notes
- Unless specified, all input parameters mentioned in the APIs are required APIs
Authentication
Access Token Based Using the API key, you can generate an access token to be used for authentication in all other APIs. The access token is valid for 8 hours.
URL
POST https://app.prod.gteam.com/gteam/app/1.0/auth
REQUEST BODY ATTRIBUTES emailAddress string Login email address key string API Key
RESPONSE ATTRIBUTES token string Authentication Token
EXAMPLE REQUEST BODY
1. { 2. "emailAddress": "[email protected]", 3. "key" : "wJVOlWAgR5ZncCZBOTTN6kR5Znc0ODFmRTlVOlFRckxtak9qUm9Z" 4. }
EXAMPLE SUCCESS RESPONSE
HTTP 200 OK
1. { 2. "token": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0MTE2MjYyMDksInN1YiI6IlFRckxtak9qUm9ZIiwidX NlcklkIjoiTS1kV3VqSk5RWEEiLCJpc3MiOiInYXBpLmd0ZWFtLmNvbSciLCJqdGkiOiJEeWZ3NDgxZkU5VSIs InNJZCI6IlVOSUpISjh4VXpBIiwiaWF0IjoxNDExNTk3NDA5fQ.roDQ7ingV4egNPNktyFye11RL9h- LXtiRwqJfFv-ztk" 3. } Cookie based Use this API to simulate cookie based login, which can be used with all further API calls and in this case you do not need API key.
URL
POST https://app.prod.gteam.com/gteam/app/sync/login/password_based
REQUEST BODY ATTRIBUTES emailAddress string Login email address password string User password
EXAMPLE REQUEST BODY
1. { 2. "emailAddress": "[email protected]", 3. "password" : "xxxxxxxx" 4. }
EXAMPLE SUCCESS RESPONSE
HTTP 200 OK with cookies Project
List of Project Locations
Returns list of project locations. The “origin” value is used to determine the base URL for subsequent APIs. This is called on the master pod.
URL
GET https://app.prod.gteam.com/gteam/app/1.0/regions
RESPONSE ATTRIBUTES pod integer Pod Id isMaster boolean Boolean to indicate if the pod is the master pod origin string Base URL to access the pod (Add protocol to the value) location string Pod location
EXAMPLE SUCCESS RESPONSE
1. [ 2. { 3. "podId": "Dyfw481fE9U", 4. "isMaster": true, 5. "origin": "//app.prod.gteam.com", 6. "location": "northAmerica" 7. }, 8. { 9. "podId": "pNCBBwArq-g", 10. "isMaster": false, 11. "origin": "//app.prod.gteam.com", 12. "location": "europe" 13. } 14. ]
List of Projects Returns a list of projects from the project location (defined by “origin”)
URL
GET https:
Id string Project Identifier
Name string Project name rootId string Root folder Identifier for the project
Image string Project image URL
Location string Project location lastVisited date Timestamp of last visit by the user making the request
Modified date Timestamp of last modification by any user
Created date Timestamp when the project was created createdBy object User that created the project
Size string Total project size noOfFiles integer Total number of files in project noOfVersions integer Total number of versions across all files/folders in the project noOfUsers integer Total number of users in the project
EXAMPLE SUCCESS RESPONSE
1. [ 2. { 3. "id": "M-dWujJNQXA", 4. "name": "Demo project", 5. "rootId": "tadQfUkLbrU", 6. "image": "/gteam/static/img/icons/no_projects_light_110.png", 7. "location": “northAmerica”, 8. "lastVisited": 1410412870000, 9. "modified": 1396485986000, 10. "created": 1396485986000, 11. "createdBy": { 12. "id": "M-dWujJNQXA", 13. "name": "imti gt-global s", 14. "email": "[email protected]" 15. }, 16. "size": "10.38 MB", 17. "noOfFiles": 5, 18. "noOfVersions": 5, 19. "noOfUsers": 2 20. } 21. ] Get Project Info URL
GET https:
PATH PARAMETERS projectId string Project Identifier
QUERY PARAMETERS
Boolean to fetch additional details [size, noOfFiles, fullyLoaded boolean Optional noOfVersions, noOfUsers]
RESPONSE ATTRIBUTES
See here [Response Attributes for Project content API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Project content API]
Create Projects URL
GET https:
REQUEST BODY ATTRIBUTES name string Project name
RESPONSE ATTRIBUTES
See here [Response Attributes for Project content API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Project content API] Folder
Folder contents Returns a list of folders and files in a given folder
URL
GET https:
PATH PARAMETERS folderId string Folder identifier to fetch children for
QUERY PARAMETERS projectId string Project identifier
RESPONSE ATTRIBUTES id string Folder Identifier versionId string Version identifier name string Folder name projectId string Project identifier parentVersionId string Parent folder version identifier parentId string Parent folder identifier hasChildren boolean Boolean value indicating if folder is empty type string Type of object (Valid values are [‘FILE’, ‘FOLDER’]) modified date Timestamp of last modification by any user modifiedBy object User that last modified the folder createdOn date Folder creation timestamp createdBy object User that created the project size string Folder size thumbnailUrl string Image URL
EXAMPLE SUCCESS RESPONSE
1. [ 2. { 3. "id": "3cIuFv8lfic", 4. "versionId": "3cIuFv8lfic", 5. "name": "Documents", 6. "projectId": "upZz8FMYa6k", 7. "parentVersionId": "xrHjrY6muOc", 8. "parentId": "xrHjrY6muOc", 9. "hasChildren": true, 10. "type": "FOLDER", 11. "modified": 1401231929000, 12. "modifiedBy": { 13. "id": "W1G1WjZPULI", 14. "name": "Karthik R", 15. "email": "[email protected]" 16. }, 17. "createdBy": { 18. "id": "W1G1WjZPULI", 19. "name": "Karthik R", 20. "email": "[email protected]" 21. }, 22. "createdOn": 1401231929000, 23. "size": "3.31 MB", 24. "thumbnailUrl": [ 25. "/gteam/static/img/icons/folder_60.png" 26. ] 27. } 28. ]
Folder contents by path Returns a list of folders and files in a given folder
URL
GET https:
QUERY PARAMETERS path string Folder path, starting with root folder (Ex: /samples/3dfiles) projectId string Project identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for Folder content API] Create Folder URL
POST https:
REQUEST BODY ATTRIBUTES name string Folder name parentId string Parent folder identifier projectId string Project Identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for Folder content API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Folder content API]
Get Folder Details Fetch details of the specified versionId
URL
GET https:
PATH PARAMETERS versionId string Folder identifier
QUERY PARAMETERS projectId string Project Identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for Folder content API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Folder content API] Get Folder versions Fetch all versions of the specified versionId
URL
GET https:
PATH PARAMETERS versionId string Folder Identifier
QUERY PARAMETERS projectId string Project Identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for Folder content API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Folder content API]
Rename Folder Rename a folder given the latest versionId
URL
POST https:
REQUEST BODY ATTRIBUTES name string Folder name id string Folder identifier versionId string Version identifier projectId string Project Identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for Folder content API]
EXAMPLE SUCCESS RESPONSE See here [Response Attributes for Folder content API]
POSSIBLE RESPONSE CODES
INVALID_OPERATION_OLD_REVISIO If versionId specified is not latest versionId N
Delete Folder URL
DELETE https:
PATH PARAMETERS folderId string Folder Identifier
EXAMPLE SUCCESS RESPONSE
HTTP 204 No Content
File
Upload File URL
POST https:
QUERY PARAMETERS projectId string Project identifier parentId string Parent folder identifier
REQUEST BODY ATTRIBUTES filename string File name
This is a multi-part request body, add the following header Content-Type multipart/form-data
RESPONSE ATTRIBUTES
See here [Response Attributes for Folder content API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Folder content API]
Get File Details Fetch details of the specified versionId
URL
GET https:
PATH PARAMETERS versionId string File identifier
QUERY PARAMETERS projectId string Project Identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for Folder content API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Folder content API]
Get File versions Fetch details of the specified versionId
URL
GET https:
PATH PARAMETERS versionId string File identifier to fetch versions for QUERY PARAMETERS projectId string Project Identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for Folder content API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Folder content API]
Download File URL
GET https:
QUERY PARAMETERS projectId string Project identifier versionId string Version identifier
This returns a stream for the file, add the following header to the request
Content-Type application/octet-stream
RESPONSE
HTTP 200 OK
Checkout Files URL
POST https:
REQUEST BODY ATTRIBUTES
Array of ids of files/folders to checkout
In case of folder ids, the API will recursively checkout files under that folder EXAMPLE REQUEST BODY
1. ["pT06-8_AzZE","LcJWPwE3YI4"]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for File content API]
POSSIBLE RESPONSE CODES
FILE_ALREADY_CHECKED_OUT If file is already checked out by same user
FILE_CHECKED_OUT_BY_ANOTHER_USER If file is already checked out by another user
Checkin Files URL
POST https:
REQUEST BODY ATTRIBUTES
Array of ids of files/folders to check-in
In case of folder ids, the API will recursively check-in files under that folder
EXAMPLE REQUEST BODY
1. ["pT06-8_AzZE","LcJWPwE3YI4"]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for File content API]
POSSIBLE RESPONSE CODES
FILE_NOT_CHECKED_OU If file is not checked out T
Rename File Rename a file given the latest versionId
URL POST https:
REQUEST BODY ATTRIBUTES name string New name id string File identifier versionId string Version Identifier projectId string Project Identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for Folder content API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Folder content API]
POSSIBLE RESPONSE CODES
INVALID_OPERATION_OLD_REVISIO If versionId specified is not latest versionId N
Delete File Delete the file for the specified versionId
URL
DELETE https:
PATH PARAMETERS versionId string Version identifier
QUERY PARAMETERS projectId string Project identifier
RESPONSE
HTTP 204 No Content
ToDo
List of ToDos URL
GET https:
QUERY PARAMETERS projectId string Project identifier
RESPONSE ATTRIBUTES id string Todo Identifier label string User friendly identifier description string Description dueDate date Due date objectStatusDto object Object to represent Todo status (details below) priorityDto object Object to represent Todo priority (details below) modified date Last modification timestamp modifiedBy object User that modified the Todo created date Todo creation timestamp createdBy object User that created the Todo projectId string Project Identifier
NESTED OBJECT DETAILS objectStatusDto – id string Status label Identifier Status value - Valid options are ["NEW", "IN_PROGRESS", label string "RESOLVED", "BLOCKED", "CLOSED"] sequence integer Sort order (read-only) priorityDto – id string Status label Identifier Status value - Valid options are ["LOW", "NORMAL ", "HIGH", label string "CRITICAL"] sequence integer Sort order (read-only)
EXAMPLE REQUEST BODY
1. [ 2. { 3. "id": "pKvW7zKEIRk", 4. "label": "DEMO-23", 5. "description": "missing column", 6. "dueDate": null, 7. "objectStatusDto": { 8. "id": "Dyfw481fE9U", 9. "label": "NEW", 10. "sequence": 1 11. }, 12. "priorityDto": { 13. "id": "3UUWLWca4SQ", 14. "label": "HIGH", 15. "sequence": 6 16. }, 17. "projectId": "upZz8FMYa6k", 18. "createdBy": { 19. "id": "M-dWujJNQXA", 20. "name": "imti gt-global s", 21. "email": "[email protected]" 22. }, 23. "modifiedBy": { 24. "id": "M-dWujJNQXA", 25. "name": "imti gt-global s", 26. "email": "[email protected]" 27. }, 28. "created": 1411582930000, 29. "modified": 1411582930000 30. } 31. ]
Create ToDo URL
POST https:
OPTIONAL REQUEST BODY ATTRIBUTES dueDate date Due date [Example Format: 2014-10-29T07:00:00.000Z] priorityDto object Object to represent Todo priority
RESPONSE ATTRIBUTES
See here [Response Attributes for Todo Listing API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Todo Listing API]
Comment
List of Comments URL
https:
QUERY PARAMETERS projectId string Project identifier
Object identifier [VersionId of File/Folder or ToDo Id, depending on objectId string object type] objectType string Object type – Valid options are ["FILE", "FOLDER ", "TODO"]
RESPONSE ATTRIBUTES id string Comment Identifier objectId string Object Identifier [VersionId of File/Folder or ToDo Id, depending on object type] objectType string Object type – Valid options are ["FILE", "FOLDER ", "TODO"] description string Description modified date Last modification timestamp modifiedBy object User that modified the Comment created date Comment creation timestamp createdBy object User that created the Comment
EXAMPLE REQUEST BODY
1. [ 2. { 3. "id": "qiZymj5TbzY", 4. "description": "Image missing on page 3", 5. "createdBy": { 6. "id": "eX9gwJqSe8I", 7. "name": "Imtiyaz S", 8. "email": "[email protected]" 9. }, 10. "created": 1413846301000, 11. "objectId": "jzdQBWZ1q5U", 12. "objectType": "FOLDER" 13. }, 14. { 15. "id": "IaFXVwzc3Dk", 16. "description": "Good find.", 17. "createdBy": { 18. "id": "eX9gwJqSe8I", 19. "name": "Imtiyaz S", 20. "email": "[email protected]" 21. }, 22. "created": 1413846298000, 23. "objectId": "jzdQBWZ1q5U", 24. "objectType": "FOLDER" 25. } 26. ] POSSIBLE RESPONSE CODES
OBJECT_NOT_FOUND If object of “objectType” specified in request is not found If object of “objectType” specified in request does not belong OBJECT_NOT_IN_PROJECT to specified project
UNSUPPORTED_TYPE If “objectType” is not supported Create Comment URL
POST https:
REQUEST BODY ATTRIBUTES description String Description Object Identifier [VersionId of File/Folder or ToDo Id, depending on objectId String object type] objectType String Object type – Valid options are ["FILE", "FOLDER ", "TODO"] projectId String Project Identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for Comments Listing API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Comments Listing API]
Edit Comment URL
PATCH https:
REQUEST BODY ATTRIBUTES description string Description id string Comment Identifier projectId string Project Identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for Comments Listing API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Comments Listing API]
Delete Comment URL DELETE https:
PATH PARAMETERS commentId string Comment Identifier
RESPONSE
HTTP 204 No Content
Release
List of Releases URL
GET https:
QUERY PARAMETERS projectId string Project Identifier Required
Release status - Valid options are ["OPEN", "SENT", string Optional status "RECEIVED"]. If excluded, will return all statuses
RESPONSE ATTRIBUTES id string Release Identifier name string Release name Status value - Valid options are ["OPEN", "SENT", status string "RECEIVED"] projectId string Project identifier notes string Release notes dueDate date Release due date recipients array List of user objects createdBy object User that created the release created date Release creation timestamp modifiedBy object User that modified the release modified date Release modification timestamp
Get Releases details URL
GET https:
PATH PARAMETERS releaseId string Release Identifier projectId string Project Identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for Releases Listing API]
EXAMPLE SUCCESS RESPONSE
See here [Response Attributes for Releases Listing API]
List of Release Files Returns list of files included in the release
URL
GET https:
QUERY PARAMETERS projectId string Project Identifier releaseId string Release Identifier
RESPONSE ATTRIBUTES
See here [Response Attributes for File content API]
EXAMPLE SUCCESS RESPONSE See here [Response Attributes for File content API]
Model
Get Model Alignment Get the alignment for the specified versionId
URL
GET https:
PATH PARAMETERS versionId string File identifier
RESPONSE ATTRIBUTES id string Model offset id. Array of matrix Row major 4x4 transformation matrix. double
Model unit is mm.
EXAMPLE RESPONSE BODY
1. { 2. "id": "Skd-09NiKrg", 3. "matrix": [ 4. 0.999999, 5. -0.000781397, 6. 0.00117874, 7. 25.4, 8. 0.000999999, 9. 0.980066, 10. -0.198668, 11. 50.8, 12. -0.001, 13. 0.198669, 14. 0.980066, 15. 101.6, 16. 0, 17. 0, 18. 0, 19. 1 20. ] 21. }
Set Model Alignment Set the alignment for the specified versionId
URL
POST https:
PATH PARAMETERS versionId String File identifier
RESPONSE ATTRIBUTES id String Model offset id.
Array of matrix Row major 4x4 transformation matrix. double
Model unit is mm.
EXAMPLE REQUEST BODY
1. { 2. "matrix": [ 3. 0.999999, 4. -0.000781397, 5. 0.00117874, 6. 25.4, 7. 0.000999999, 8. 0.980066, 9. -0.198668, 10. 50.8, 11. -0.001, 12. 0.198669, 13. 0.980066, 14. 101.6, 15. 0, 16. 0, 17. 0, 18. 1 19. ] 20. } EXAMPLE RESPONSE BODY
1. { 2. "id": "Skd-09NiKrg", 3. "matrix": [ 4. 0.999999, 5. -0.000781397, 6. 0.00117874, 7. 25.4, 8. 0.000999999, 9. 0.980066, 10. -0.198668, 11. 50.8, 12. -0.001, 13. 0.198669, 14. 0.980066, 15. 101.6, 16. 0, 17. 0, 18. 0, 19. 1 20. ] 21. } B. Public 3D Viewer APIs (Token based) Public Viewer APIs are token based JavaScript APIs can be used to manipulate the viewer which can be embedded into any other web based application.
1. Prerequisites: SSL Server Setup
Enabling SSL on Apache [SSL is required for Trimble Connect API use]
This tutorial uses XAMPP version 3.2.x
1.a.1. Install XAMPP Server
XAMPP URL: https://www.apachefriends.org/index.html
1.a.2. Open the following file in a plain text editor such as notepad or gedit [not Excel]:
C:\xampp\apache\makecert.bat
1.a.3. Change the second line in the file from: set OPENSSL_CONF=./bin/openssl.cnf to: set OPENSSL_CONF=./conf/openssl.cnf
1.a.4. Open the windows command prompt [or the terminal if using OSX or GNU Linux]
1.a.5. In the command prompt, point to the Apache installation folder by entering the following command: cd C:\xampp\apache
1.a.6. Create a new SSL certificate by entering the following command: makecert
* Enter values when prompted.
* The 'Common Name' should be the domain name or IP address of the XAMPP server.
* For local testing, 'localhost' can be entered.
* The 'challenge password' is an optional entry that can be left blank if preferred.
1.a.7. Enter the following text into the file 'C:\xampp\apache\conf\extra\httpd-xampp.conf' at the top line:
RewriteEngine On
# Redirect -xampp folder to https
RewriteCond %{HTTPS} !=on
RewriteCond %{REQUEST_URI} xampp
RewriteRule ^(.*) https:--%{SERVER_NAME}$1 [R,L]
# Redirect -phpMyAdmin folder to https
RewriteCond %{HTTPS} !=on
RewriteCond %{REQUEST_URI} phpmyadmin
RewriteRule ^(.*) https:--%{SERVER_NAME}$1 [R,L]
# Redirect -security folder to https
RewriteCond %{HTTPS} !=on RewriteCond %{REQUEST_URI} security
RewriteRule ^(.*) https:--%{SERVER_NAME}$1 [R,L]
# Redirect -webalizer folder to https
RewriteCond %{HTTPS} !=on
RewriteCond %{REQUEST_URI} webalizer
RewriteRule ^(.*) https:--%{SERVER_NAME}$1 [R,L]
1.a.8. In the file 'C:\xampp\apache\conf\httpd.conf,' search for the text 'LoadModule rewrite_module modules/mod_rewrite.so' and check that there is no pound # sign in front of it.
The line should read: LoadModule rewrite_module modules/mod_rewrite.so and not: #LoadModule rewrite_module modules/mod_rewrite.so
1.a.9. Go to the Windows start menu and search for 'certmgr.msc'
1.a.10. In the CertMgr menu, click on 'Trusted Root Certification Authorities'
1.a.11. Right-click on 'Certificates' listed in the 'Object Type' list, and select 'All Tasks > Import'
1.a.12. Browser to the folder 'C:\xampp\apache\conf\ssl.crt,' select the file 'server.crt,' and click 'open'.
1.a.13. Accept default settings when clicking through the file import menu.
1.a.14. Close the CertMgr tool [Click File > Exit]
1.a.15. Start XAMPP server and click 'Start' in the Actions list next to 'Apache'
1.a.16. Check https://localhost/ in a web browser to verify that SSL is set up.
2. Authentication
2.a. Log into Trimble Connect.
2.b. Go to https://app.prod.gteam.com/gteam/app/useraccounts/me/apikey to retrieve your API key.
2.c. Retrieve an access token to use when making API calls.
Access tokens can be retrieved by sending a post request to the URL: https://app.prod.gteam.com/gteam/app/1.0/auth
The following PHP sample code performs a POST request to retrieve an API key.
$url = https://app.prod.gteam.com/gteam/app/1.0/auth";
$data = array(
'emailAddress' => "[email protected]",
'key' => "Z-hf79kjhty79Hhfj84Dhy3HJYyf6580kHTR6gu8"
);
$options = array(
'http' => array(
'method' => 'POST',
'content' => json_encode( $data ),
'header'=> "Content-Type: application/json\r\n" . "Accept: application/json\r\n"
)
);
$context = stream_context_create( $options );
$result = file_get_contents( $url, false, $context );
$response = json_decode( $result );
echo $response->token;
The access token will look similar to the following string: eyJhbGciOiJIUzI1NiJ9.eyJhfi6YHITYsInN1YiI6IlFRckxtak9qUm9ZIiwid
XNlcklkIjoiZUJBdzA3NEIyVmciLCJpc3MiOiInYXBpLmd0ZWFtLmNvb
SciLCJqdGkiOiJxMkk3ZHdEV3JuTSIsInNJZCI6IkhONDhkX2FxVmtN
IiwiaWF0IjoxNDA2NzY3Mzk2fQ.DgxYhi8f4TVviykDBBVQ
The PHP code above, placed within a php file, should be called to retrieve an access token before proceeding to step 3 below.
The php file can be called with an ajax post, or other method.
See Appendix item 5.b for sample code.
3. Instantiating the Embedded Viewer
3.a. Include the following javascript file: https://app.prod.gteam.com/gteam/static/gteam/viewer/embed.js
3.b. Specify a DOM node to embed the Trimble Connect viewer. var ViewerNode = document.getElementById("GTeamViewer");
3.c. Specify the embedded viewer's configuration.
This can be done by using a javascript array as described below:
var viewer_data = { "domNode": node
, "title": "Viewer Title to Display on Web Page"
, "noProperties": false
, "noLeft": false
, "debug": true
, "height": 850
, "width": 1500
, "gteamOrigin" : encodeURIComponent("https://app.prod.gteam.com")
, "projId" : "Dyfw481fE9U"
, "objects" : "M-dWujJNQXA"
, "mashup" : "Dyfw481fE9U"
, "accessToken" : accessTokenString
, "class" : "embeddedViewFrame"
, "onInitialized": function() { optional: place code here } //callback function to run code on viewer load };
See Appendix item 5.a for embedded viewer parameter definitions.
3.c.2. Retrieving the Project ID
Log into Trimble Connect, and within the project display the file within the Trimble Connect viewer.
The extract the Project ID from the page URL https://app.prod.gteam.com/gteam/app/#project,viewer&id=BYRvifmFaUk&mashup=3d9LXbVDCqs&o bjects=X6Uw9Wd7kz8 project,viewer&id=BYRvifmFaUk
BYRvifmFaUk
3.c.3. Retrieving the Objects ID https://app.prod.gteam.com/gteam/app/#project,viewer&id=BYRvifmFaUk&mashup=3d9LXbVDCqs&o bjects=X6Uw9Wd7kz8 objects=X6Uw9Wd7kz8
X6Uw9Wd7kz8
3.c.4. Retrieving the Mashup ID https://app.prod.gteam.com/gteam/app/#project,viewer&id=BYRvifmFaUk&mashup=3d9LXbVDCqs&o bjects=X6Uw9Wd7kz8 mashup=3d9LXbVDCqs
3d9LXbVDCqs
3.d. Create an instance of the Trimble Connect embedded viewer var viewer = new EmbeddedViewer(viewer_data);
Full example for embed viewer
4. API List
The following API calls are available for use with the Embedded Viewer:
API calls that request data will receive the data within a callback function
addToSelection Description
Append objects to the current selection
API viewer.addToSelection(str_arr,bl_recrsv);
Input Parameters
Input 1: String array of external object IDs
Input 2: Boolean true/false for retrieval of nested objects within the specified objects
Output
None
getExternalIds Description
Get the collection of external IDs corresponding to a string array of internal IDs.
API viewer.getExternalIds(str_arr,callback);
Input Parameters
Input 1: String array of internal object IDs
Input 2: A callback function with 1 argument, e.g. function(stringArrayResult){ }
Output
Callback function containing returned string array
getObjectCount Description
Get the total number of objects loaded in the viewer
API viewer.getObjectCount(callback);
Input Parameters
Input: A callback function with 1 argument, e.g. function(integerResult){ }
Output
Callback function containing returned integer
getObjectsRange Description
Get an array of external IDs for objects within the specified index range
API viewer.getObjectsRange(int_from,int_to,callback);
Input Parameters
Input 1: The starting index [integer] of the collection of object IDs to retrieve
Input 2: The ending index [integer] of the collection of object IDs to retrieve
Output
Callback function containing a string array of external IDs
getProperties Description
Get the properties of objects specified in a string array of external IDs
API viewer.getProperties(str_arr,callback);
Input Parameters
Input 1: A string array of external IDs Input 2: A callback function with 1 argument, e.g. function(stringArrayResult){ }
Output
Callback function containing a string array of external IDs
getSelected Description
Get the collection of currently selected objects
API viewer.getSelected(callback);
Input Parameters
Input: A callback function with 1 argument, e.g. function(stringArrayResult){ }
Output
Callback function containing a string array of external IDs
hide Description
Hide the specified objects
API viewer.hide(str_arr);
Input Parameters
Input: A string array of external IDs
Output
None
highlight Description
Highlight the specified objects
API viewer.highlight(str_arr,bl_recrsv);
Input Parameters
Input 1: A string array of external IDs
Input 2: Boolean true/false for highlighting of nested objects within the specified objects
Output
None
hideType Description
Hide all objects of the specified type within the viewer [Walls, Doors, etc]
API viewer.hideType(str_type);
Input Parameters
Input: String name of object type
Output
None
getInternalIds Description
Get the collection of internal IDs corresponding to a string array of external IDs
API viewer.getInternalIds(str_arr,callback);
Input Parameters
Input 1: A string array of external IDs
Input 2: A callback function with 1 argument, e.g. function(stringArrayResult){ }
Output
Callback function containing a string array of internal IDs
removeFromSelection Description
Remove specified objects from the current selection
API viewer.removeFromSelection(str_arr,bl_recrsv);
Input Parameters
Input 1: A string array of external IDs
Input 2: Boolean true/false for removing nested objects within the specified objects
Output
None
reset Description
Reset object visibility, object selection, and camera position
API viewer.reset();
Input Parameters
Input: None
Output
None
selectByName Description
Select object by name
API viewer.selectByName(str_name,bl_recrsv);
Input Parameters Input 1: The string name of the object to select
Input 2: Boolean true/false for selecting nested objects within the specified object
Output
None
setMaterial Description
Set the material property in Trimble Connect for the specified objects
API viewer.setMaterial(str_arr,str_material,bl_recrsv);
Input Parameters
Input 1: A string array of external IDs
Input 2: The string name of the material to set
Input 3: Boolean true/false for applying material to nested objects within the specified object
Output
None
setSelection Description
Select a specified set of objects, and clear the prior selection if any.
API viewer.setSelection(str_arr,bl_recrsv);
Input Parameters
Input 1: A string array of external IDs
Input 2: Boolean true/false for selecting nested objects within the specified objects
Output
None
show Description
Show the specified objects within the viewer
API viewer.show(str_arr);
Input Parameters
Input 1: A string array of external IDs
Output
None
showType Description
Show all objects of the specified type within the viewer [Walls, Doors, etc]
API viewer.showType(str_type);
Input Parameters
Input: String name of object type
Output
None
zoom Description
Zoom to the specified objects within the viewer
API viewer.zoom(str_arr);
Input Parameters
Input 1: A string array of external IDs Output
None
5. Appendix
5.a Glossary
Embedded Viewer Parameters: title //viewer title to display on web page noProperties //display properties panel noLeft //display left panel debug //output debug messages height //viewer height width //viewer width gteamOrigin //Trimble Connect home page URL projId //Project ID - refer to 2.c.2. objects //Objects ID - refer to 2.c.3. mashup //Mashup ID - refer to 2.c.4. accessToken //access token string class //object class name onInitialized //callback function
External ID The external ID is the unique ID of each object that is assigned to it by Trimble Connect.
The external ID of each object is unique for each file revision.
The external ID is used to identify objects within a specific revision of a file.
Internal ID The internal ID is the unique ID of each object that is assigned to it by its authoring environment. This ID is usually persists through file revisions for objects that are unmodified.
5.b Javascript php post request code:
The sample code below uses a jquery http://jquery.com/ ajax post to call a php file.
$.ajax({
type: 'POST',
url: 'auth/get_actkn.php',
async: false,
success: function(result){
console.log("Access Token = " + result);
},
error: function(){
}
});
The sample code below uses a dojo http://dojotoolkit.org/ javascript post to call a php file.
define([
"dojo/_base/declare","dojo/request"
], function(declare, request){
return declare(null, {
getAccessToken: function() {
return request.post("auth/get_actkn.php", {
}).then(function(result) {
return result; //the access token is returned here
}); }
});
});