Introduction

introduction
This document will help you get started using the Trimble APIs. This section gives an overview of the Trimble Ag APIs and how they are used.

API Credentials

Obtain your API credentials by sending a request to tas_api@trimble.com.

Exchange data with Trimble Ag Software

  • An organization is the basic structure that segregates user data. An organization typically represents the business entity that manages the resources (fields, equipment, personnel, materials) used in a farming operation.Your customers must have a Trimble Ag account (created at www.TrimbleAg.com). Each user account will have access to one or more organizations.
  • Your users must approve your application to access their data within www.trimbleag.com either through the OAuth process you initiate, or directly through www.trimbleag.com.
  • To allow your application to access your customer’s Connected Farm data, you must do the following:
    • Obtain an access token 
    • Once the client application has an access token, you will use the other Trimble Ag API endpoints.

Authentication and Authorization

Overview and When to Use

Nearly all API partners are set up to use the standard Authentication and Authorization. Unless you are informed otherwise, this is how your API Connection will be set up and you should use these authentication and authorization instructions (the Alternate Authentication and Authorization will not work for your API setup).<br><br>This configuration option utilizes user-level authorization. This authentication and authorization applies when multiple users log into the 3rd party application connected via API (your application) and every user should have access to the different organizations that they individually have access to through different Trimble Ag Software logins.<br><br><strong>Definition of Variables</strong>
VariablesDefinition
TID - Trimble Identity {{Env Auth root}}Production authentication - https://id.trimble.com
Trimble Ag API {{Env Data root}}Production data - https://cloud.api.trimble.com/Trimble-Ag-Software/externalApi/3.0
{{yourAppName}}The application name provided by Trimble that is assigned to your application
{{yourClientId}}The GUID (unique identifier) provided by Trimble that is assigned to your application
{{authenticationCallbackURL}}The URL that users should be returned to after authorizing Organizations for data access in www.trimbleag.com (must be an exact match to a URL in the list of valid authenticationCallback URLs you provide)
{{logoutURL}}The URL that users should be returned to after logging out of the application www.trimbleag.com (must be an exact match to a URL in the list of valid logout URLs you provide)
{{authorizationRedirectURL}}The URL that users should be redirected to after authorizing Organizations for data access at www.trimbleag.com (must be an exact match to a URL in the list of valid authorizationRedirectURLs you provide)
{{authProvider}}The returned value of the authentication provider that was accessed
{{TIDAuthCode}}The code generated by the TID system that you can exchange for an access, refresh and ID token from TID.
This code may only be used once and expires after 10 minutes.
{{accessToken}}The JWT token that is used to access data endpoints.
The access token has a 1 hour expiration.
{{idToken}}The JWT token contains additional information about the user who was authenticated in TID.
{{refreshToken}}The token has a 7-day expiration that can be exchanged for a new access token.

Authentication

Authentication
In order for your application to access data within an Organization, the Trimble user must approve your application in an Authorization step, but in order to discover if a user has authorized your application you need to go through an OAuth process to gain access to the data that is scoped to that user.<br><br>These flow diagrams illustrate how you can use the APIs to allow third-party software to send data to and receive data from the Connected Farm software.

Authorization/Authentication API data flow diagram

User Authorization Code

Step 1

The first step of the OAuth process is to send the user to log into Trimble’s identity management system in order to obtain an authorization code. This code will be valid for 10 minutes.

URL

Use this GET call to redirect the user to TID.

{{Env Auth root}}/oauth/authorize?scope={{yourAppName}} openid&response_type=code&redirect_uri={{authenticationCallbackUrl}}&client_id={{yourClientId}}

Step 2

After the user logs into TID they will be returned to your application via the following URL:

{{authenticationCallbackUrl}}?code={{TIDAuthCode}}&identity_provider={{authProvider}}

Authentication Token API

This API can be used for authentication from a third party client application or a web service to obtain an access token to use for subsequent method calls as described in the Common authentication token. This API also returns an ID for identification and a refresh token for re-authentication after the access token expires. <strong>The authentication token is valid for 1 hour and the refresh token is valid for 9 days. The refresh token is a single-use token that becomes invalid after use.</strong>

URL

This URL should be used to obtain an authentication token and the refresh token.

POST {{Env Auth root}}/oauth/token

Input Example

The following is an example of the parameters to help illustrate the definition. The string of characters after the word Basic would be the result of base 64 encoding MyProvidedClientId:MyClientSecret which you would replace with your own values.

POST: https://id.trimble.com/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic TXlQcm….
grant_type=authorization_code&code=sd3ds…&client_id=e3rdfF…&redirect_uri=https://mydomain.com/oauthreturn

The header and request body values are defined in the following tables.

Header Values

This web service expects you to post a URL- Form- Encoded string in the request body, containing the following fields in the header:

AttributeDescriptionValuesRequired
AuthorizationBasic Auth using Base64 encoded value of provided ClientID:ClientSecretBasic {Encoded value goes here}Y
Content-TypeSpecifies the request content typeapplication/x-www-form-urlencodedY

Request Body Values

This web service expects you to post a URL- Form- Encoded string in the request body, containing the following fields:

AttributeDescriptionValuesRequired
grant_typeRequired value to identify authentication typeauthorization_codeY
codeThe authorization code returned from the OAuth process{{TIDAuthCode}}Y
client_idThe GUID provided to you{{yourClientId}}Y
redirect_uriAn exact match to one of the URLs provided to Trimble by you to return to your app after logging in.{{authenticationCallbackUrl}}Y

Response

This service acknowledges with an HTTP code 200 for success (OK) and all other HTTP codes for failure. 

In addition to the 200 HTTP code, the web service responds with a JSON formatted document with the following fields to provide either confirmation of the receipt or an error:

AttributeDescriptionValues
access_tokenThe security token that is used on subsequent requests.This token will be a long string generated with each new POST to this endpoint.
token_typeIdentifier of what type of token has been returned.Will always be “bearer”
expires_inTime in seconds until expiration.Returns “3600”.  
Each call to the endpoint results in a new token lasting 60 minutes.
Please cache and reuse the token for calls within 60 minutes of the last authentication.
id_tokenJWT token to provide additional information about the user.This token will be a long string generated with each new POST to this endpoint.
refresh_tokenToken to exchange for a new access token and refresh token.This token will be a string generated with each new POST to this endpoint.
errorThe Error title of the error being shown.
error_descriptionError description to help understand the error provided.

Response example (tokens truncated)

Content-Type: application/json; charset=utf-8
{
    "token_type": "bearer",
    "expires_in": 3600,
    "access_token": "eyJ0eXAiOiJKV1….",
    "refresh_token": "NAwdjwEX6vj….",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhb….",
}

Logout

(Optional): If you wish to log the user out of TID and return them to your application utilize the following URL:

URL

{{Env Auth root}}/oauth/logout?id_token_hint={{IdToken}}
&post_logout_redirect_uri={{yourLogoutUrl}}

Refresh Authentication Token API

URL

Use the following URL to obtain a refresh token once the authentication token expires.

POST  {{Env Auth root}}/oauth/token

Input example

The following is an example of the parameters to help illustrate the definition. The string of characters after the word Basic would be the result of base 64 encoding MyProvidedClientId:MyClientSecret are replaced with your own values.

Header Values

The web service expects you to post a URL- Form- Encoded string in the body, containing the following header values:

AttributeDescriptionValuesRequired
AuthorizationBasic Auth using Base64 encoded value of provided ClientID:ClientSecretBasic {Encoded value goes here}Y
Content-TypeSpecifies the request content type.application/x-www-form-urlencodedY

Body Values

The web service expects you to post a URL-Form-Encoded string in the body, containing the following fields:

AttributeDescriptionValuesRequired
grant_typeRequired value to identify authentication type.refresh_tokenY
refresh_tokenThe refresh code returned from the Authentication Token [link inserted here] endpoint.{{RefreshToken}}Y
tenantDomain*Required valuetrimble.comY

Response

The service sends an acknowledgement with HTTP code 200 for success (OK) and any other HTTP code for failure.

In addition to the HTTP 200 code, the web service responds with a JSON formatted document with the following fields to provide either confirmation of the receipt or an error:

AttributeDescriptionValues
access_tokenThe security token that needs to be used on subsequent requests.This token will be a long string generated with each new POST to this endpoint.
token_typeIdentifier of what type of token must be returned.Will always be “bearer”
expires_inTime in seconds until expiration.Will return 3600.  Each call to the endpoint will result in a new token lasting 60 minutes, please cache and reuse the token for calls within 60 minutes of the last authentication.
id_tokenJWT token to provide additional information about the user.This token will be a long string generated with each new POST to this endpoint.
refresh_tokenToken to exchange for a new access token and refresh token.This token will be a string generated with each new POST to this endpoint.
errorError title
error_descriptionError description to help understand the error provided.

Response example

Content-Type: application/json; charset=utf-8
{
    "token_type": "bearer",
    "expires_in": 3600,
    "access_token": "eyJ0eXAiOiJKV1....",
    "refresh_token": "NAwdjwEX6vj....",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhb....", 
}

Common Authentication Token

All REST calls made available by the Connected Farm data center will require proper authentication. To achieve this, a Trimble Identity access token must be passed to validate that the caller has permission. All subsequent calls are validated by Trimble’s TID service and the access token should be prefixed with Bearer in the Authorization header. <br>The following is an example of the parameters to help illustrate the definition:
GET:
https://cloud.api.trimble.com/Trimble-Ag-Software/externalApi/2.0/Organizations/
Authorization: Bearer 
eyJ0eXAiOiJK....

Authorization of Organizations

In order to gain access to an Organization’s data, a user of that Organization must authorize your application to do so. This is accomplished through an OAuth process, where the user will be directed to a Trimble Ag website. Here, the user is required to sign in, approve your application and select which Organizations to approve for access.

Step 1

From your application, or via another process of your choice, redirect the user that would be approving your application to the following URL:

Production URL

https://www.trimbleag.com/ThirdPartyAccess/ThirdPartyAuthorizationRedirect?clientid={{yourClientId}}&redirectionUrl={{authorizationRedirectUrl}}

Step 2

Users who are not currently logged in are directed to Trimble’s login service for www.trimbleag.com.

Step 3

The logged-in user is presented with an Authorization page that uses the logo provided to Trimble as part of the Authorization setup.

Step 4

Once your application is authorized for that user, the user will be presented with a list of Organizations to which they have access and can select the Organizations to which they want your application to have access as well.  Selecting a Trimble Ag Advisor Organization provides access to all the child Organizations that the logged- in user has access to for that Advisor Organization.

Step 5

Once the user hits the save button after selecting the Organizations, they will be redirected to the return URL that you provided during setup of your application with Trimble.

Step 6

Once the user has authorized you to access their data, you can expect the following:

  • The OrgIds authorized for that user will appear in the GET config/organizations result set.
  • The returned results will be scoped to the token for that user.  It is your responsibility to use the proper user token for matching the user in your system and use the refresh token before it expires.
  • If the refresh token expires before you use it to acquire a new token, your system will need to acquire a new User Authorization Code to exchange for a new access and refresh token.
  • User Authorization Code - Valid for 10 mins, Access Token - Valid for 1 hour, Refresh Token - Valid for 9 days.

For each user that approves usage of their data, it is your responsibility to ensure that only the authorized user has access to the authorized data in your application.

Alternate Authentication and Authorization

Overview and When to Use (Alternate)

This configuration only applies to specific API partners. You would be informed if you are set up to use the Alternate Authentication and Authorization process. If you are not setup to use the Alternate Authentication and Authorization process you can skip this section.<br>This configuration option utilizes application-level authorization.  This authentication and authorization applies when only a single entity logs into the 3rd party application connected via API (your application) and every user should have access to the same authorized organizations in the Trimble Ag Software.

Definition of variables

VariablesDefinition
TID - Trimble Identity {{Env Auth root}}Production authentication - https://id.trimble.com
{{yourAppName}}The application name provided by Trimble that is assigned to your application.
{{yourClientId}}The GUID (unique identifier) provided by Trimble that is assigned to your application.
{{accessToken}}The JWT token that is used to access data endpoints.
The access token has a 1 hour expiration.

Authentication (Alternate)

alternate-authentication
In order for your application to access data within an Organization, the Trimble user must approve your application in an Authorization step, but in order to discover if a user has authorized your application you need to go through an OAuth process to gain access to the data that is scoped to that user.<br> <br>These flow diagrams illustrate how you can use the APIs to allow third-party software to send data to and receive data from the Connected Farm software.

Authorization / authentication API data flow diagram:

Authentication Token API (Alternate)

This API can be used for authentication from a third party client application or a web service to obtain an access token to use for subsequent method calls as described in the Common authentication token. This API also returns an ID for identification and a refresh token for re-authentication after the access token expires. <strong>The authentication token is valid for 1 hour and the refresh token is valid for 9 days. The refresh token is a single-use token that becomes invalid after use.</strong>

URL

This URL should be used to obtain an authentication token and the refresh token.

POST {{Env Auth root}}/oauth/token

Input Example

The following is an example of the parameters to help illustrate the definition. The string of characters after the word Basic would be the result of base 64 encoding MyProvidedClientId:MyClientSecret which you would replace with your own values.

POST: https://id.trimble.com/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic TXlQcm....
grant_type=client_credentials&scope=MyAppName

The header and request body values are defined in the following tables.

Header Values

This web service expects you to post a URL- Form- Encoded string in the request body, containing the following fields in the header:

AttributeDescriptionValuesRequired
AuthorizationBasic Auth using Base64 encoded value of provided ClientID:ClientSecretBasic {Encoded value goes here}Y
Content-TypeSpecifies the request content typeapplication/x-www-form-urlencodedY

Parameter Values

The web service expects the following fields as query string parameters:

AttributeDescriptionValuesRequired
grant_typeRequired value to identify authentication typeclient_credentialsY
scopeThe name of your application{{yourAppName}}Y

Response

This service acknowledges with an HTTP code 200 for success (OK) and all other HTTP codes for failure.

In addition to the 200 HTTP code, the web service responds with a JSON formatted document with the following fields to provide either confirmation of the receipt or an error:

AttributeDescriptionValues
access_tokenThe security token that is used on subsequent requests.This token will be a long string generated with each new POST to this endpoint.
token_typeIdentifier of what type of token has been returned.Will always be “bearer”.
expires_inTime in seconds until expiration.Returns “3600”.  
Each call to the endpoint results in a new token lasting 60 minutes.
Please cache and reuse the token for calls within 60 minutes of the last authentication.
errorError title
error_descriptionError description to help understand the error provided.

Response example (tokens truncated)

Content-Type: application/json; charset=utf-8
{
    "token_type": "bearer",
    "expires_in": 3600
    "access_token": "eyJ0eXAiOiJKV1....",  
}

Authorization of Organizations (Alternate)

In order to gain access to an Organization’s data, a user of that organization must authorize your application to do so. This is accomplished through a special page where the user will be required to sign in, approve your application and select which Organizations to approve for access.

Step 1

As a user of www.trimbleag.com with access to the Organization you would like to authorize, open the following URL in a browser (replacing {{yourClientId}} with the Client Id provided to you):

https://www.trimbleag.com/ThirdPartyAccess/ThirdPartyAuthorizationRedirect?clientid={{yourClientId}}

Step 2

Users who are not currently logged in are directed to Trimble’s login service for www.trimbleag.com.

Step 3

The logged-in user is presented with an Authorization page to approve your application.

Step 4

Once your application is authorized for that user, the user will be presented with a list of Organizations to which they have access and can select the Organizations to which they want your application to have access as well.  Selecting a Trimble Ag Advisor Organization provides access to all the child Organizations that the logged- in user has access to for that Advisor Organization.

Step 5

Once the user has authorized you to access their data, you can expect the following:

  • The OrgIds authorized for that user will appear in the GET config/organizations result set.
  • The returned results will be scoped to the list of orgs authorized to be accessed by your application.
  • When the access token expires you will need to call the Authentication Token endpoint again to obtain a new access_code to use with the APIs.
  • Access Token - Valid for 1 hour.
Organizations

Organizations

Use this method from a third-party client application or web service to obtain a list of approved organizations for the access token.  For each user that approves Organization data it is your responsibility to ensure that only that authorized user has access to that data in your application.
Resources

Overview

resources-overview
The Resources APIs enable users to create clients, farms, fields, boundaries, guidance lines, landmarks, and contacts in other applications; share those with Trimble Ag Software; and potentially send them to connected Trimble displays. New resources and/or edits from Trimble Ag Software or Trimble Displays can also be sent back to the other applications.

Clients

Clients
Clients are the highest level of the organization hierarchy for a Field. Clients contain Farms.

Farms

Farms
Farms are the middle level of the organization hierarchy for a Field. Farms are contained within Clients, and contain Fields.

Fields

Fields
Fields define a piece of ground and are used to organize the work that happens on that ground. Fields are contained within Farms. Fields contain Boundaries, Field Extents, Guidance Lines, Landmarks, Crop Seasons, Prescriptions, Files, and Tasks.

FieldExtents

FieldExtents
A Field Extent is a property of a field and is primarily used for record-keeping. On a Trimble display Field Extents can be viewed, but not edited, using the Field Manager. In the Trimble Ag web and mobile tools Field Extents can be viewed and edited from the Fields List. As Field Extents are properties of Fields, they share the same ID as the Field.<br>

Boundaries

Boundaries are the functional extent of a field and are used for operational workflows. On a Trimble display Boundaries can be viewed and edited using the Field Manager. On the web Boundaries are viewed from Landmarks page within a Crop Zone.

GuidanceLines

GuidanceLines
Guidance Line are a navigation aid used by precision ag displays to define where to drive in a field. Guidance Lines are contained within Fields.

Landmarks

Landmarks are features that are points of interest within a Field. Landmarks are contained within Fields.

Contacts

Contacts represent people that are associated with the running of an operation. Contact information can include detail such as contact detail,  whether the contact is an Equipment Operator, and whether the person has Trimble Display access when Operator Sign-in is on for an Org.

OperatorGroups

Operator Groups are an optional classification that can be created and apply to Contacts. These assignments could be based on Contacts that perform the same function, are in the same region, or for any other reason the users choose.
Crop Zones

Overview

cropZones-overview
Crop Zones are used to organize information about the crop being grown in a field in a particular year. Crop Zones include information about the crop, boundary for that crop, and what tasks occurred in relation to that crop in a particular growing season.

MasterCrops

Master Crops represent crops that can assigned to be grown in a Crop Zone.

CropSeasons

Crop Seasons represent the combination of a year and a Master Crop being grown in a field within a particular year.

CropZones

Crop Zones represent a Crop Season for a Field. Crop Zones are contained within Fields. Equipment Activities and Crop Zone Activities are contained within Crop Zones.

CropZoneExtents

A Crop Zone Extent is a property of a Crop Zone and represents the boundary for a Crop Zone. When created in the Trimble Ag UI, Crop Zone Extents will initially be an exact match of the Field Extent and can then be modified by the user. As Crop Zone Extents are properties of Crop Zones, they share the same ID as the Crop Zone.
Materials

Overview

materials-overview
The Materials APIs allow users to create, export, and track different inputs that are associated with applications in a Crop Zone.

Materials

Materials represent different inputs that are applied to Crop Zones. Materials type examples include chemical, fertilizer, and seed. Material details could include information such as form, rate, and manufacturer.
Units

Overview

units-overview
The Units APIs provide detailed information about the units that are returned with different calls.

Units

The Units APIs return Units for different data types such as Materials, Contracts, or Layer Sensors.
Vehicles, Implements, Devices

Overview

devices-overview
The Vehicles, Implements, Devices APIs are used to create and capture information about equipment that is used to complete work. This information may be associated with jobs that are completed (as available from the EquipmentActivity or CropZoneActivity APIs) in a Crop Zone. Further, The Devices APIs can enable sending recommendations directly to the devices that will execute those recommendations in the field (using the Prescriptions APIs).

Devices

Devices represent displays that are used for in-field operational workflows and are contained within Organizations.

Vehicles

Vehicles represent machinery that is used to complete fieldwork. Vehicles have a Manufacturer, Equipment Type, and may optionally be included in Equipment Groups. Devices may be assigned to Vehicles.

VehicleTypes

Vehicle Types are assigned to Vehicles and are used to account for the general vehicle function. Example Vehicle Types include “Combine”, “Spayer”, “Tractor-4WD” and “Generic”.

EquipmentGroup

Equipment Groups are an optional classification that can be created and apply to Vehicles. These assignments could be based on Vehicles that serve the same function, are in the same region, or for any other reason the user chooses.

EquipmentManufacturers

Equipment Manufacturers are applied to Vehicles and represent the maker of the Vehicle.

Implement

An Implement represents an equipment that is used to execute work in the field. Implements may optionally include Operation Type and/or Equipment Group.
Prescriptions

Overview

prescriptions-overview
The Prescriptions APIs allow users to send prescriptions from partner applications to Trimble Ag Software and, if desired, directly to a field device.

Prescriptions

Prescriptions represent a recommendation file. The zip file should contain at least one set of .shp, .dbf, and .shx files with the polygons and rates. The projection for the prescription shapefiles should be GCS WGS84. The user does not need to include a .prj file in the zip file. The polygons should only have one exterior cycle and may contain one or more interior cycles (holes). The .dbf should have at least one numeric column of data that contains the corresponding rates for each polygon.  Multiple sets of shapefiles may be included in a single .zip file, but all the .dbf files must have the same rate column name for the display to recognize the rate column.
Tasks

Overview

tasks-overview
The Tasks APIs enable users to forward job data from devices and Trimble Ag Software to 3rd parties.

EquipmentActivity

The Equipment Activity endpoints provide detailed information on tasks (i.e. in-field jobs) created from precision ag displays. This includes tasks from Trimble displays and other equipment manufacturer display data that has been imported to a Trimble account. <br><br><strong>The as-applied or sensor data associated with an Equipment Activity task is available from the Layers endpoints.</strong><br><br>Within the optional Equipment Activity query parameters, the startDate and endDate parameters are based on the ending time for a task. Therefore, if the task end UTC is equal to or past the query parameter startDate UTC, we return the task. Likewise, if the task end UTC is equal to or before the query filter EndDate UTC, we return the task.<br>

Layers

The Layers endpoints provide access to the layer and sensor data associated with Equipment Activity tasks. Descriptions of the Layers endpoints are below:<br><br>- Gets a list of Layers for the EquipmentActivityId - returns a list of all layers for an Equipment Activity Task<br>- Get a Layer by Id - returns details about a single layer for an Equipment Activity Task<br>- Get list of sensors on a layer - returns a list of sensors for a single layer. Sensors could include values such as target rate, applied rate, or speed.<br>- Get list of samples on a layer - returns geometry in GeoJSON format with associated sensor values for a single layer.

OperationType

Operation Types represent the different types of operations for the Equipment Activities and Crop Zone Activities. These are generic for all Orgs. Operation examples would be “Spreading” or Spraying”.

OperationSubtype

Operation Subtypes represent the different types of operations subtypes for the Equipment Activities and Crop Zone Activities. These would be customized by individual users. Examples could be “First Spraying” or “Second Spraying”.

CropZoneActivity

Crop Zone Activities represent manual field records that were created in the Trimble mobile or online application. Crop Zone Activities do not have machine coverage or as-applied data.

Files

Task files from field devices that are stored in the Trimble Ag Software are available to be downloaded through the Files API. Files will be zip files with either an AgGPS (FMX/FMX+) or AgData (Precision-IQ) folder of files. Once downloaded these files may need to be combined and will need to be parsed using the Trimble plugins for the AgGateway ADAPT framework. More information about ADAPT can be found at adaptframework.org.<br><br>Note that the Files endpoint provides the same data that is available from the EquipmentActivity endpoints, but in an unprocessed and encrypted format.<br><br><strong>Retrieve list of files from devices</strong><br><br>Use this resource to obtain a list of files that are associated with a given organization. Each file returned will contain metadata about the file, and an Id plus a URL that can be used to directly download the file.

Download specific files

Use the temporaryAccessUri returned the FileManagement/v3/Files API response to download individual files.

ADAPT

Overview

adapt-introduction
ADAPT – the Agricultural Data Application Programming Toolkit – is a framework for converting<br>agronomic data between various formats. This toolkit is the result of a collaborative industry effort and includes multiple pieces, including both an open source core framework and a set of plugins. The core framework consists of a common data model, a plugin manager, and a set of utilities for managing units of measure and data representations. The plugins are assemblies which convert data between that common data model and various other data formats.<br>

AdaptToken

The ADAPT Data Model

The entire functionality of ADAPT is centered on converting data to and from a common Application<br>Data Model. As an application developer, this means you only need to integrate with one data model.<br>The Application Data Model is contained in the AgGateway.ADAPT.ApplicationDataModel.dll assembly.<br>

Plugin Manager

The plugin manager is the main entry point when using ADAPT as an SDK. It detects and identifies available plugins, determines which plugin is appropriate for reading a given data source, and marshals plugins and their dependencies as needed. It is contained in the AgGateway.ADAPT.PluginManager.dll assembly.

Representation

The representation assembly, AgGateway.ADAPT.Representation.dll, includes utility classes to help work with units of measure and data representations (similar in concept to ISO DDI’s).

Plugins

Each plugin is responsible for translating data between the Application Data Model and a specific external data format. The Trimble plugin supports both the AgGPS and AgData file formats.

Getting Started

Referencing ADAPT

You can reference ADAPT using NuGet by referencing the package at https://www.nuget.org/packages/AgGatewayADAPTFramework/  If you would rather not use a NuGet client, you can download any version of the package from nuget.org and extract it using a zip utility. In addition to executables, the ADAPT package contains a “Resources” folder that contains RepresentationSystem.xml and UnitSystem.xml. This entire Resources folder needs to be copied to your application’s \bin directory for the representation system to work.

Application Data Model

The ADAPT Application Data Model is being documented by the AgGateway committee responsible forthe ADAPT project. The project homepage is found at http://www.adaptframework.org/

Plugin Manager

The Plugin Manager is used to retrieve and marshal plugins. The PluginFactory must be passed a filesystem directory where the plugin assemblies are stored. Note that while there may be subdirectories (i.e., a folder for each manufacturers’ plugins), the plugin manager will only recurse one level of subdirectories. In other words, passing “C:\AdaptPlugins\” to the PluginFactory would cause it to discover plugins inside both “C:\AdaptPlugins\” and first level subdirectories like “C:\AdaptPlugins\Trimble\”, but not in “C:\AdaptPlugins\Trimble\AgGPS\”. Following is sample code which shows how to load plugins and import a datacard.

PluginFactory factory = new PluginFactory("directory containing plugins");
List<string> pluginNames = factory.AvailablePlugins;
foreach(string pluginName in pluginNames)
{
  IPlugin plugin = factory.GetPlugin(pluginName);
  if(plugin.IsDataCardSupported("datacard path")
  {
    ApplicationDataModel dataModel = plugin.Import("datacard path");
    return dataModel;
  }
}

Representation

The Representation namespace includes two sets of helper API’s the Unit of Measure System and the Representation System. Together, they form something similar to the ISO DDI system of describing data. A Representation describes the type of data – such as harvest moisture, implement section state, or the GPS receiver offsets. A Unit of Measure provides both the syntax for specifying a unit and the ability to convert between different units of measure or perform arithmetic operations. You can explore the Representations and the units of measure in the included RepresentationSystem.xml and UnitSystem.xml files. Note that these xml files are used by the Representation namespace; if you reference the ADAPT Representation assembly, you will need to include those xml files as resources which are copied to your application’s executing directory.

Unit of Measure System

The simplest way to retrieve unit of measure objects is using static methods on the UnitSystemManager class. To retrieve a UnitOfMeasure instance, pass a unit code to UnitSystemManager.GetUnitOfMeasure(“unit code”). You may also use UN Rec20 unit codes, via UnitSystemManager.FromUNRec20Code(“UN unit code”).

To help use the units of measure: Once you create a NumericValue, which consists of a value and unit, we offer helper methods for arithmetic operations or unit conversions. If you add the namespace: using AgGateway.ADAPT.Representation.UnitSystem.ExtensionMethods; You will then have access to NumericalValue.Add(double value), NumericalValue.ConvertToUnit(UnitOfMeasure unit), and other helper methods.

Trimble ADAPT Plugins

The ADAPT plugins to read Trimble display data are

  • Trimble.Ag.ADAPT.Plugins.AgData.dll - PIQ and related displays
  • Trimble.Ag.ADAPT.Plugins.AgGPS.dll - FMX and related displays

Initialization

Trimble plugins require a license token to be validated in the initialization process that is acquired through the Trimble Cloud API system. Applications will need to be registered in the Trimble Cloud system to access this API.

To simplify the process of authenticating and requesting the token, functions have been added to the Trimble plugins that will perform the API calls for a 3rd party application to request a new token. The function is:

AdaptTokenClient.GetTokenAsync( {AppName}, {AppClientID}, {AppSecret} )
  • AppName: Name of calling application as registered in Trimble Cloud
  • AppClientID: GUID assigned to application by Trimble Cloud
  • AppSecret: Application password assigned by Trimble Cloud

The token structure returned will have the following:

  • token: string with encrypted token value to be used in Initialize function
  • expiration: date and time the token expires. Tokens can be reused up to the expiration date.

Datacard Paths

The Trimble plugin will support multiple datacard paths. It will support a path that includes the AgGPS or AgData directory (ex: C:\TrimbleData\AgGPS). It will also support passing the parent directory as well (ex: C:\TrimbleData).

Please note that the plugin will not support both file formats at once. If you have a datacard path that has both an AgGPS and AgData directory, it will only read the AgGPS information.

Other Information

Bookmarks

The maximum number of records returned for most calls is 1000. In cases where the potential number of records in a response exceeds the maximum number of records that can be returned, a bookmark attribute is included in the response. The token associated with that bookmark then can be passed as a query parameter in a subsequent call to obtain the next set of records. For example, if the total number of records associated with some request is 1,500, the first response will include 1,000 records and a bookmark attribute. A following call including the token from that bookmark would return the remaining 500 records.<br><br>An example of the bookmark attribute as part of a response is shown below.<br><br><img width="722" height="93" src="https://lh6.googleusercontent.com/mogue_-8AvRE88K1FJxBKEPveylNbPIIDZ-blwjFkIW0USjrrBNrHwig6hGo8W64XYFggdsareAJZG5lx0WsiOHyE2UVRigLN4sY62S-exR85CwNqAqyemhp2SUbnruMH7ggGwT6x6i92u6j9g">

Links

Links are Trimble Ag’s implementation of <a href="https://restfulapi.net/hateoas/">HATEOAS</a>. These links are useful in discovering additional actions and endpoints that are associated with a particular call. If you do not wish to include links in the response, these can be disabled by using the query parameter includeLinks=false in the request.<br><br>The following is an example of links being returned for the Clients GET endpoint:
"links": [
               {
                   "href": "https://cloud.dev.api.trimblecloud.com/Trimble-Ag-Software/externalApi/rogue/3.0/resources/e540056a-8f68-4c4f-ba96-8d88e9ecaea8/clients/ebb17f5c-5b06-4e89-8174-125c4fc463f9",
                   "rel": "GetClient",
                   "method": "GET"
               },
               {
                   "href": "https://cloud.dev.api.trimblecloud.com/Trimble-Ag-Software/externalApi/rogue/3.0/resources/e540056a-8f68-4c4f-ba96-8d88e9ecaea8/clients",
                   "rel": "CreateClient",
                   "method": "POST"
               },
               {
                   "href": "https://cloud.dev.api.trimblecloud.com/Trimble-Ag-Software/externalApi/rogue/3.0/resources/e540056a-8f68-4c4f-ba96-8d88e9ecaea8/clients/ebb17f5c-5b06-4e89-8174-125c4fc463f9",
                   "rel": "UpdateClient",
                   "method": "PUT"
               },
               {
                   "href": "https://cloud.dev.api.trimblecloud.com/Trimble-Ag-Software/externalApi/rogue/3.0/resources/e540056a-8f68-4c4f-ba96-8d88e9ecaea8/clients/ebb17f5c-5b06-4e89-8174-125c4fc463f9/retire",
                   "rel": "RetireClient",
                   "method": "PATCH"
               },
               {
                   "href": "https://cloud.dev.api.trimblecloud.com/Trimble-Ag-Software/externalApi/rogue/3.0/resources/e540056a-8f68-4c4f-ba96-8d88e9ecaea8/clients/ebb17f5c-5b06-4e89-8174-125c4fc463f9/unretire",
                   "rel": "UnretireClient",
                   "method": "PATCH"
               },
               {
                   "href": "https://cloud.dev.api.trimblecloud.com/Trimble-Ag-Software/externalApi/rogue/3.0/resources/e540056a-8f68-4c4f-ba96-8d88e9ecaea8/farms",
                   "rel": "GetFarms",
                   "method": "GET"
               }
           ]