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

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

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

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

- Step 1: GET - Get the list of Equipment Activities
This will return the list of Equipment Activity tasks for an Organization in the Trimble Agriculture Cloud.
-- API Call: {{BaseURL}}/tasks/{{OrgId}}/equipmentactivities
-- Path Variable: Org ID
-- Response: A successful GET request will result in 200 OK status code along with the response body that includes a list of Equipment Activities and their IDs. The bookmark token in the response can be used in the query parameter in the subsequent API call to obtain the set of remaining records. You can find more details on bookmarks here.

- Step 2: GET - Get the list of Layers for an Equipment Activity ID
This will return the list of Layers for a single Equipment Activity task.
-- API Call: {{BaseURL}}/tasks/{{OrgId}}/layers?equipmentActivityId={{EquipmentActivityId}}
-- Path Variable: Org ID
-- Query Parameter: Equipment Activity ID (obtained from Step 1 response)
-- Response: A successful GET request will result in 200 OK status code along with the response body that includes a list of Layers and their IDs.

- Step 3: GET - Get the list of Samples on a Layer
This will return the list of Samples (i.e. locations) along with the Sensors and associated values for a single Layer.
-- API Call: {{BaseURL}}/tasks/{{OrgId}}/layers/{{layerId}}/samples
-- Path Variables: Org ID, Layer ID (obtained from Step 2 response)
-- Response: A successful GET request will result in a 200 status code along with the Samples and Sensor values associated with the Layer.

- Step 1: POST - Initiate Prescription Import
Use this endpoint to create a prescription record with the prescription information.
-- API Call: {{BaseURL}}/prescriptions/{{OrgId}}/rx/importjob/
-- Path Parameter: Org ID
-- Response: A successful POST request will result in the 200 status code along with the Job ID in the response body.

- Step 2: PATCH - Upload zip file for Prescription import
Use this endpoint to upload the Prescription zipped file to the Trimble Ag Software and/or directly to a field device.
-- API Call: {{BaseURL}}/prescriptions/{{OrgId}}/rx/importjob/{{jobId}}
-- Path Parameter: Org ID, Job ID (obtained from Step 1 response)
-- Response: When the PATCH request goes through it will result in a 204 No Content status code with empty response body.

- POST - Create a Field
This endpoint will create a Field in the Trimble Ag Software.
-- API Call: {{BaseURL}}/resources/{{OrgId}}/fields/
-- Path Variable: Org ID
-- Response: A successful POST request will result in the 200 OK status code with the Field ID and entity links in the response body. These links can be used to make API calls associated with the newly created Field. You can find more details on the entity links here.

- POST - Create a Boundary
This endpoint can be used to create a new Boundary.
-- API Call: {{BaseURL}}/resources/{{OrgId}}/boundaries
-- Path Variable: Org ID
-- Request Body: The field ID would be the ID of the field in which you want to create a new Boundary.
-- Response: A successful POST request will result in the 200 OK status code along with the Boundary ID and entity links in the response body. These links can be used to access the endpoints associated with the newly created Boundary. You can find more details on the entity links here.

- POST Create a Guidance Line
This endpoint will create a new Guidance Line in the Trimble Ag Software.
-- API Call: {{BaseURL}}/resources/{{OrgId}}/guidancelines
-- Path Variable: Org ID
-- Request Body: The field ID would be the ID of the field in which you want to create a new Guidance Pattern.
-- Response: A successful POST request will result in the 200 OK status code along with the Guidance Line ID and entity links in the response body. These links can be used to access the endpoints associated with the newly created Guidance Line. You can find more details on the entity links here.

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

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:

Request Body Values

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

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:

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….",
}

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:

Body Values

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

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:

Response example

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

GET:
https://cloud.api.trimble.com/Trimble-Ag-Software/externalApi/3.0/config/organizations
Authorization: Bearer 
eyJ0eXAiOiJK....

Definition of variables

Authorization / authentication API data flow diagram:

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:

Parameter Values

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

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:

Response example (tokens truncated)

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

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.

Download specific files

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

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.

• Vehicle position and position history to inform logistics decisions
• Vehicle work status and history to understand job performance and identify issues
• Vehicle sensor information available though the public CAN to prevent breakdowns and assist technicians in machine maintenance.

By connecting to this API 3rd party applications that address operations and logistics can execute real-time management and detailed post-operation analysis to understand and improve equipment and operator productivity.

Trimble Display telematics data availability requires:

• A Farmer Core or other base license is applied the display’s Trimble Ag Software Organization
• A Display Connection License is applied to the display
• The display is  connected to the cloud
• The Utilization App is started on the display

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