The Trimble Connected Farm is an independent, brand agnostic platform that connects infield devices and operational workflows, to more efficiently execute crop production plans and collect the most robust dataset in the industry.<br><br>In addition to delivering customer value around the Operational Workflow, the Trimble Ag Platform connects and enables compatibility with non-Trimble platforms and applications that deliver additional value to the farmer. Enabling farmers to complete workflows that involve solutions from multiple technology providers is critical to our customers, especially in cases where 3rd party applications address unique regional farming practices, are preferred by local advisor networks, offer enhanced local technology support or address local regulatory policies.<br><br>Trimble Ag APIs are REST APIs that enable this value delivery.

The Trimble Ag Software API allows users to accomplish a variety of tasks:<br>

• Align Client/Farm/Field, Boundaries, Guidance Lines, and Landmarks between  3rd party applications and Trimble Ag Software/Trimble Displays 
• Send Prescriptions from 3rd party applications to Trimble Ag Software/Trimble Displays 
• Send as-applied data from Trimble Displays to 3rd party applications
• Many others…

• Data flow within the Trimble Ag Platform - Data from 3rd party applications is sent to Trimble Ag Software and may then be automatically or manually sent to connected Trimble Displays. Data from connected Trimble Displays will be sent to Trimble Ag Software and then may be sent to 3rd party applications.

• In Trimble Ag Software, Organizations are 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. Each Trimble Ag Software user account will have access to one or more organizations.
• Trimble Displays supported for most Trimble Ag Platform data exchange include TMX-2050, GFX-750, GFX-350, XCN-2050, XCN-1050, and XCN-750

• To exchange data between a connected 3rd party application and a Trimble Ag Software Organization the Organization must have a Trimble Ag Software base license (e.g. Farmer Core). 
• To connect to a Trimble Ag Software Organization a Trimble Display must have a Trimble Ag Software display license (e.g. Display Connection).

Step-by-step instructions on how to get started with this API.

• Create Application
  
  • Request Trimble Agriculture API credentials by filling out the form here.
    
  • Grant Type Options - your application will be set up using one of the two options below. This decision depends on who will be accessing the API through your application.
    
    • Authorization Code Grant
      
      • Operation - allows confidential and public clients to exchange an authorization code for an access token via a trusted back channel.
        
      • Use Case - this configuration option utilizes user-level authorization. This is applicable when multiple users (i.e. your customers) 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.
        
    • Client Credentials Grant
      
      • Operation - allows clients to obtain an access token outside of the context of a user with a secured environments.
        
      • Use Case - this configuration option utilizes application-level authorization. This is applicable when only a single entity (i.e. your business) 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.
        
• For access to a Trimble Ag demo Org and demo data please send a request to ag_api@trimble.com.

• Authenticate your application to gain an access token. Note that your process will differ depending on whether your application is setup to use the Authorization Code Grant or Client Credentials Grant  (see the instructions below).
• Users authorize access to data in Organizations through an OAuth process you initiate (see the instructions below).
• Connect to endpoints for accessing authorized organizations and exchanging data (see API documentation).

See below for API workflows that cover some common use cases. Note there are additional APIs available as part of these workflows that can provide information such as other related data or the status of a process. Furthermore, there are many other use cases supported by the Trimble Ag APIs.

• Send a prescription to a Trimble display
  
  • Devices GET to see what Trimble Displays are available in an Org
  • Prescriptions POST to create a new prescription record
  • Prescriptions PATCH to append a prescription shapefile to the prescription record
• Send fields, boundaries, and guidance lines to Trimble Ag Software and sync them to a Trimble Display by enabling AutoSync from the web
  
  • Fields POST to create a new field
  • Boundaries POST to create a new boundary
  • Guidance Line POST to create a new guidance line
• Access as-applied from a Trimble display
  
  • Equipment Activity GET to get a list of Trimble tasks
  • Layers GET to get list of layers for a Trimble task
  • Layers Samples GET to get the sensor value for each location in a layer

Overview-and-When-to-Use-1

Nearly all API partners are set up to use the Authorization Code Grant for Authentication. 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 Client Credentials Grant will not work for your API setup).<br><br>This configuration option utilizes user-level authorization. This authentication 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>

Variables	Definition
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 from OAuth login at TID (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

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}}

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:

Attribute	Description	Values	Required
Authorization	Basic Auth using Base64 encoded value of provided ClientID:ClientSecret	Basic {Encoded value goes here}	Y
Content-Type	Specifies the request content type	application/x-www-form-urlencoded	Y

Request Body Values

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

Attribute	Description	Values	Required
grant_type	Required value to identify authentication type	authorization_code	Y
code	The authorization code returned from the OAuth process	{{TIDAuthCode}}	Y
client_id	The GUID provided to you	{{yourClientId}}	Y
redirect_uri	An 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:

Attribute	Description	Values
access_token	The security token that is used on subsequent requests.	This token will be a long string generated with each new POST to this endpoint.
token_type	Identifier of what type of token has been returned.	Will always be “bearer”
expires_in	Time 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_token	JWT token to provide additional information about the user.	This token will be a long string generated with each new POST to this endpoint.
refresh_token	Token to exchange for a new access token and refresh token.	This token will be a string generated with each new POST to this endpoint.
error	The Error title of the error being shown.
error_description	Error 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}}

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:

Attribute	Description	Values	Required
Authorization	Basic Auth using Base64 encoded value of provided ClientID:ClientSecret	Basic {Encoded value goes here}	Y
Content-Type	Specifies the request content type.	application/x-www-form-urlencoded	Y

Body Values

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

Attribute	Description	Values	Required
grant_type	Required value to identify authentication type.	refresh_token	Y
refresh_token	The refresh code returned from the Authentication Token [link inserted here] endpoint.	{{RefreshToken}}	Y
tenantDomain	*Required value	trimble.com	Y

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:

Attribute	Description	Values
access_token	The 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_type	Identifier of what type of token must be returned.	Will always be “bearer”
expires_in	Time 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_token	JWT token to provide additional information about the user.	This token will be a long string generated with each new POST to this endpoint.
refresh_token	Token to exchange for a new access token and refresh token.	This token will be a string generated with each new POST to this endpoint.
error	Error title
error_description	Error 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....", 
}

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....

Overview-and-When-to-Use-2

This configuration only applies to specific API partners. You would be informed if you are set up to use the Client Credentials Grant. If you are not setup to use the Client Credentials Grant process you can skip this section.<br><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

Variables	Definition
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.

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-2

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:

Attribute	Description	Values	Required
Authorization	Basic Auth using Base64 encoded value of provided ClientID:ClientSecret	Basic {Encoded value goes here}	Y
Content-Type	Specifies the request content type	application/x-www-form-urlencoded	Y

Parameter Values

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

Attribute	Description	Values	Required
grant_type	Required value to identify authentication type	client_credentials	Y
scope	The 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:

Attribute	Description	Values
access_token	The security token that is used on subsequent requests.	This token will be a long string generated with each new POST to this endpoint.
token_type	Identifier of what type of token has been returned.	Will always be “bearer”.
expires_in	Time 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.
error	Error title
error_description	Error 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....",  
}

<strong>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.</strong>

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:

URL for Authorization Code Grant

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

URL for Client Credentials Grant

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 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

This step only applicable for Authorization Code Grant

Once the user hits the save button after selecting the Organizations, they will be redirected to the authorization redirect 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:

Below applies to Authorization Code Grant

• 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.

Below applies to Client Credentials Grant

• 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.

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.

clients-farms-fields-overview

The Client, Farm, Field APIs enable users to create Clients, Farms, and Fields in other applications; share those with Trimble Ag Software; and send them to connected Trimble displays. Clients, Farms, and Fields from Trimble Ag Software or Trimble Displays can also be sent back to the other applications.

resources-overview

The Field Resources APIs enable users to create Field Extents, Boundaries, Guidance Lines, and Landmarks in other applications; share those with Trimble Ag Software; and send them to connected Trimble displays. Field Extents, Boundaries, Guidance Lines, and Landmarks from Trimble Ag Software or Trimble Displays can also be sent to other applications.

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.

vehicles-implements-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).

contacts-overview

The Contacts APIs enable users to create Contacts and Operator groups in other applications; share those with Trimble Ag Software; and send them to connected Trimble displays. Contacts and Operator Groups from Trimble Ag Software can also be sent to other applications.

management-zone-overview

The Management Zone APIs are used for managing spatial zones. These zones may be used as part of field management practices such as the creation and application of a variable rate prescription.

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.

workorders-overview

The Work Orders API enables users to plan, assign, and communicate jobs to be completed across the farm. Work Orders can remotely preconfigure Precision-IQ Display tasks or may be completed manually.<br><br>Work Orders are associated with Crop Zones.

tasks-overview

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

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.

materials-overview

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

 

inventory-overview

The Inventory APIs are used for record-keeping purposes and enable users to track current material inventory and create new material inventory.

commodities-overview

The Commodities API enables users to manage harvest storage locations, contracts, and storage transactions.

analytics-overview

The Analytics API endpoints enable integrations with 3rd party applications to allow pushing test results to and retrieving test results from Trimble Ag Software.

documents-overview

The Documents API enables users to upload and access documents. These documents may be associated with Materials, Bin Transactions, or Scouting photos.

units-overview

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

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>

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.

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.

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.

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 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"
               }
           ]