1. ADAPT Public Space

ADAPT Frequently-Asked Questions (FAQ)

Created by R. Andres Ferreyra
Last updated 2020-09-21 by Andres Ferreyra

ADAPT Team - reference this wiki page for help in filling out FAQ answers: /wiki/spaces/ADAPT/pages/74186845

General Questions

Is ADAPT ready for use in a production environment? I still see some open issues on the documentation pages.

The short answer is "YES!" (and some stakeholders have been using it in production for over a year as of June 2017). That being said, this merits a multi-point answer.

  • ADAPT is a living product; it represents an industry consensus that will change and improve over time.
  • The team released a Version 1 that is already in use (for example, by John Deere, and others) to enable interoperability. 
  • The ADAPT Team is preparing the release of Version 2, as a result of lessons learned from v1. The new version includes 
    • Better management of versions and breaking changes.
    • Improvements to the data model
    • More documentation
  • Our best answer is to invite you to start using ADAPT through “opportunistic adoption”: the most efficient way to learn how to use ADAPT and to ensure it fits your needs is to actually start using it in your integration projects.
  • Discuss your needs with the Technical Team to determine what version is best for you, and participate! You can affect the outcome by participating.

What's the value of contributing code to ADAPT?

Adoption of Field Operations data by growers has lagged behind its potential for decades.  To dramatically increase adoption system interoperability needs to be achieved at a dramatically reduced cost for the industry.  Contributing improvements to the ADAPT framework will accelerate the industry's ability to achieve this goal!

What use cases are supported by ADAPT, and what's the roadmap?

AgGateway's ADAPT Oversight Committee is currently working on outlining the steps required to implement a "Version 1" of ADAPT - which has a focus on documentation data generated by field computers (MICS) being consumed by business systems (FMIS).

What version of Visual Studio does the ADAPT project work in?

You can use either Visual Studio 2015 or Visual Studio 2017 with the ADAPT project.

Visual Studio Community 2017 is a free version available from Microsoft.

How does ADAPT handle localization / "internationalization?" (introduction to "ContextItem" system)

Since ADAPT is focused on supporting field operations based business processes, grower practices typically have local context (e.g., EPA number, ....).  It is important for ADAPT to be able to address this data, but in a way that doesn't require all aspects to be explicit in the model.  Instead, ADAPT uses a data driven "ContextItem" system - definitions of items can be sourced via the internet, anyone can propose a new definition for an item (https://api.contextitem.org/swagger).   

Will ADAPT be an international standard or will it only work in North America?

ADAPT is an open-source project to provide a mechanism for enabling global interoperability between various software and hardware applications in agriculture.  Since the plug-ins used in the solution are software libraries that can interconvert between a common object model and a given format, the given format simply needs to specify language and context. As long as a translation exists, a plug-in can be designed to accomplish the translation.  The ADAPT project uses the Eclipse Public License to ensure the project meets the needs of the global companies that are focused on improving the interoperability of field operations data systems.

I want to adopt ADAPT: Where do I start?

The developer guide and sample application cover most of the scenarios of accessing and writing data. You will need an application which can consume a .net/mono library. 

  • A guide on how to tackle the project, what steps make sense to do in what order as I implement connecting the whole framework and data model to the existing FMIS platform
  • As a terminal manufacturer creating a plugin I would like an example of an existing plugin and some guidelines on what the plugin requirements are. It may have been a while since I really looked at a FODD or anything similar so this might be all new to the development team

What is the business case for adopting ADAPT?

The ADAPT framework is focused on providing a Data Model that covers a comprehensive superset of Field Operations Data. The goal is to allow a single integration for any Farm Management Information System - FMIS and through licensing of various plugins provided by different manufacturers (of systems that produce/consume Field Operations Data) the FMIS can read/write to a wide variety of systems with little incremental effort. The scope is quite broad - beyond field computers in self propelled machines (e.g., tractors) to include irrigation control and monitoring systems (in future versions). The goal is to expand the compatibility with even more kinds of Field Operations Data going forward. As an Open Source Software project, the ADAPT Oversight Committee is focused on providing a framework that can evolve as the industry sees fit.



Why would I adopt ADAPT instead of using one of these data hubs I’ve been hearing about?

A: The real question here is why use an open-source solution instead of a pay-as-you-go commercial service. Your business has to decide what is best for you and your customers in the end. ADAPT was created to prevent the limitations of interoperability of field operations data with a goal of reducing the engineering effort required to translate a wide range of data from FMIS and MICS applications. 


And what is the difference between the i) ADAPT project, ii) the Ag Data Coalition and iii) DKE?

i) ADAPT

An open-source data model

ADAPT is an open-source project initiated by AgGateway to provide a mechanism for enabling global interoperability between various software and hardware applications in agriculture. ADAPT has two primary components:

  • A common data/object model, designed to be a superset of the ISO 11783 model and those of participating companies, and
  • A plug-in framework. Plug-ins are software libraries (proprietary or open-source, as chosen by their creator) that can interconvert between the common object model and a given format of interest.

Converting formats, however, is not enough to guarantee interoperability; a system of shared meaning is also required. For this reason, ADAPT was designed with an emphasis on unique identifiers, and the use of data-type registries and other semantic assets that can ensure that all participants in a data exchange process interpret the data in the same way. The end-goal is the OEMs and software developers will develop plug-ins to exchange data from their systems to/from the ADAPT data format – providing for free exchange of logged agronomic data, allowing for the growth of the use of Field Operations Data in Agriculture as Growers will be able to use the hardware and software of their choice to run their businesses without worry of the systems not being interoperable.

ii) Agricultural Data Coalition Repository

A neutral commercial data storage and transfer service

The goal of Agricultural Data Coalition is a create a neutral, independent data repository where farmers can securely store and control the information collected every day in the fields by their tractors, harvesters, aerial imaging and other devices. Over time, that data can then be scrubbed, synced and transmitted in an efficient and uniform way to third parties — whether they be researchers, crop insurance agents, government officials, farm managers, input providers or anyone else the farmer chooses. The agricultural data coalition will provide a privacy-ensured way for farmers to access markets; increase yields and profitability; and ensure unrestricted access to their data, services and products.

This neutral data repository also provides a secure and neutral option for sharing their data with participating land grant universities for research if they so choose. The ADC commercial repository is currently functional and connected to multiple OEM clouds for easy data transfer.  Learn more at http://agdatacoalition.org/

iii) DKE Agrirouter

A commercial data transfer hub

DKE is a non-profit consortium of equipment manufactures that provides a data exchange platform, known as Agrirouter, that allows farmers and contractors to exchange data between machinery and agricultural software applications from a wide range of manufacturers. While Agrirouter moves data between applications, it does store data. The AGRI-Router will enable the transfer of task files to and from machines based on the ISO11783 standard initially, as well as the exchange of telematics data based on the work done within AEF to define the EFDI standard. This will enable farmers to choose what data is shared from their machines with which partners and software tools. Data is never shared however unless the user sets up the permissions to enable data from compatible tools to pass through the hub. In the future the AGRI-Router plans to add support for ADAPT to enable the transfer of additional task file formats.

The data hub, which will go into operation in in the spring of 2018, is set up to charge software and application providers based on transported data volumes. DKE is a consortium of major agricultural companies, including AGCO, Amazone, Deutz-Fahr, Grimme, Horsch, Krone, Kuhn, Lemken, Pöttinger and Rauch.  Learn more at http://www.dke-data.com/en/der-agrirouter-kommt

ADAPT is open-source software; what does this mean to me and my company?

ADAPT has been developed under the Eclipse Public License v1.0  Equipment manufacturers desire an approach that can be used with Farm Management Information System (FMIS) companies anywhere in the world that they do business. An open source approach allows non-AgGateway member companies to leverage the framework, providing the ability to:
 Modify the framework to meet their commercial needs quickly, and evolve the standard interface for everyone.
 Submit modifications back for consideration to incorporate into ADAPT (which are reviewed before acceptance)
From Wikipedia: Open Source Software is “A development model (which) promotes a universal access via a free license to a product's design or blueprint, and universal redistribution of that design or blueprint, including subsequent improvements to it by anyone.”

If I Use ADAPT, which is open-source, does that mean I have to give my software away or something like that?

The short answer: NO! There are two aspects to this question. 

  1. You could be focused on creating an ADAPT plug-in for a particular data format.  Plug-in creators can license there plug-ins as they see fit (including charging for them).  That capability was an important consideration in the selection of the Eclipse Public License as the Open Source Software license which the ADAPT framework is provided under.  
  2. You could be focused on incorporating ADAPT into your company's software to make it easier for your software to read/write different data formats.  Incorporation of ADAPT does not mean that you have to i) share your software's source code and/or ii) provide your software for free.  You do have to comply with the terms of the Eclipse Public License as well as any agreements with the ADAPT plug-in providers that you have licensed.  From Wikipedia: The Eclipse Public License is designed to be a business-friendly free software license and features weaker copyleft provisions than contemporary licenses such as the GNU General Public License (GPL).[7]  

ADAPT has been developed under the Eclipse Public License v1.0  Equipment manufacturers desire an approach that can be used with Farm Management Information System (FMIS) companies anywhere in the world that they do business. An open source approach allows non-AgGateway member companies to leverage the framework, providing the ability to:
- Modify the framework to meet their commercial needs quickly, and evolve the standard interface for everyone.
- Submit modifications back for consideration to incorporate into ADAPT (which are reviewed before acceptance)


From Wikipedia: The Eclipse Public License is designed to be a business-friendly free software license and features weaker copyleft provisions than contemporary licenses such as the GNU General Public License (GPL).[7] The GNU General Public License (GNU GPL or GPL) is a widely used free software license, which guarantees end users the freedom to run, study, share and modify the software. The receiver of EPL-licensed programs can use, modify, copy and distribute the work and modified versions, in some cases being obligated to release their own changes.[8] The EPL is approved by the Open Source Initiative (OSI)[3] and is listed as a free software license by the Free Software Foundation(FSF).[2]

ADAPT Model Questions

Are there any tools to help me understand the object model?

  • ArgoUML
  • Visualizer

What's the difference between a Representation, a ContextItem, and an Observation Code?

lorem ipsum dolor

What are Context Items / Representations / Observation Codes?

I've looked at the list of ContextItems / Representations / Observation Codes and I don't see the one I need. How do I get something on the list?

asdasddasddassd

Is ADAPT a Data Transfer Tool?

ADAPT is not focused on data transmission, instead it is focused on data translation/conversion. This is not to say a plugin provider won't put a mechanism in their plugin which enables data transmission (upon use of the plugin) to a specific "cloud service." It is important for the companies that license a specific plugin to know the terms which they agree to.

Is ADAPT an API? An SDK?

ADAPT consists of two main components.

  1. ADAPT Framework - The Software Development Kit that includes the data model, APIs and other tools which can be integrated into FMIS systems under AgGateway licensing terms.

2. ADAPT Framework Plugin - a data converter for a specific data format which can be easily integrated into a specific data format which can be easily integrated into a specific instance of ADAPT. A specific plugin would be created/licensed by i) AgGateway, ii) equipment manufacturers, iii) entities (e.g., USDA), iv) FMIS companies, v) individuals, etc.

When will ADAPT be done?

Can my developers start using it now?

YES!  actively engage in using ADAPT.  If you see an opportunity to improve it please reach out to the Technical Team at adapt.feedback@aggateway.org as to the improvement that you'd like to make to the framework (best to get alignment before doing the work and submitting a pull request on GitHub).

How do you handle breaking changes?

In 2017, the ADAPT Oversight Technical Committee adopted a Branching and Versioning Policy.  The Team consulted with an Open Source Software expert as part of the development of this policy.  The entire policy can be found at ADAPT Branching and Versioning Policy 

"Breaking changes"  are defined in Wiktionary as "a change in one part of a software system that potentially causes other components to fail; occurs most often in shared libraries of code used by multiple applications. Not possible to fix old entries without a breaking change, so remap old to new in import lib."

ADAPT's Branching and Versioning Policy addresses this in the "Major pull requests handling"  section of the policy.  "Any elements which will be removed as part of this major version change must be marked as deprecated for one major version. This provides users with sufficient time to know about changes and fully prepare for the change."  

What are the available plugins?

asdasd

I'm interested in being able to read / write format X: Is there a plug-in for it?

asdasd

I'm interested in being able to read / write format X: There's no plug-in for it; what do I do now?

asdasds

I'm interested in creating a plug-in to read / write format X: How can I get started? Can anyone help me?

Interested party should attend technical meetings to get their support network built up.  

Email adapt.feedback@aggateway.org to request invitation to ADAPT Technical Team Meetings

Look at what already exists: ADM Plugin (serialization); ISO Plugin (in progress)

Make sure you completely understand your data model first.

Study and understand the ADAPT data model documentation.

(video ref) "mechanics of plugin manager" https://www.youtube.com/watch?v=MY63gGSECoI

https://www.youtube.com/watch?v=MY63gGSECoI


For users developing with Visual Studio, the availability of the Adapt Data Model and its dependiencies through NuGet makes adding ADAPT code to a project very simple.  Search NuGet package manager with "AgGateway ADAPT"

What test data is available for me to test my ADAPT integration / plugin?

1. Sample code in the tree demo - helps a lot to provide data that could be used to test an integration.  https://github.com/ADAPT/ADAPT-Samples/tree/develop/TreeDemo


3. Test utilities directory in the https://github.com/ADAPT/ISOv4Plugin/tree/develop/TestUtilities/Datacards has more real-world data examples (applied to ISO).  Pull in test data into ADAPT, serialize in the ADM plugin - provide sample files (work with it from an ADAPT objects standpoint)

I'm interested in capturing and exchanging data about a particular aspect X of field operations. How can I find out if ADAPT supports it?

For developers - dig into the code. For managers - talk to your developers.  Adaptframework.org has several videos that review various aspects of ADAPT which you may find helpful to answer this question: https://adaptframework.org/adapt-videos/

I'm interested in capturing and exchanging data about a particular aspect of field operations. ADAPT does not currently support it. What do I do now?

Communicate with the ADAPT community (specifically the Technical Committee) on the need. 

  1. There are some rough edges here. Constructive feedback is always helpful.
  2. Technical Committee meetings are Wednesdays @ 10 am CST. Send an e-mail to adapt.feedback@aggateway.org if you are interested in speaking with the Technical Committee about your identified gap in the ADAPT framework.
  3. There may be an opportunity for you to contribute to ADAPT to provide this additional capability within the ADAPT framwork, but it is best to be coordinated with the Technical Committee as there may be a need to agree on the best approach (or there may be a misunderstanding in what ADAPT supports and how it supports it - so your aspect of field operations may be supported in a different way than what you are thinking of).

What software platforms does ADAPT support?

asdasd

What are the dependencies of ADAPT on other frameworks / packages?

The framework has been built on .net framework 4.5 (mono compatible).  If you are using the ADM plugin there are two dependencies: i) package called Newtonsoft.net (a class that puts the data into a json format upon serialization) as well as ii) protobuff-net (what is used to serialize the spatial data elements)

Is there a fixed release schedule?

Note that an important part of ADAPT is data-driven, so vocabulary entries, whole vocabularies, and variable definitions can be added without users having to change versions of ADAPT in their software. This has been engineered as a very IT-department friendly feature of ADAPT.

How does ADAPT differ from ISO 11783?

The ADAPT framework incorporates a "superset" of data models used in the industry (to ensure system interoperability).  As such, the goal is to incorporate ISO requirements as part of a larger industry context.  One other important difference: the ADAPT framework has a larger scope than ISO 11783, namely more business needs related to Field Operations data than just the transactions that occur between FMIS and MICS systems.   


How does ADAPT differ from ESRI Shapefile format?

The ESRI Shapefile format has been used to exchange Field Operations data in many cases.  A key limitation to this approach is the need for the user interaction - that the various attributes contained in a shapefile need to be "mapped" to the system of interest to ensure interoperability.  This fundamental requirement creates an inherent limitation on user adoption - basically constraining usage to individuals that are comfortable managing this level of detail.  The industry will struggle to attract other participants that desire a "lower tech" solution if we continue to rely on loosely defined Shapefile attributes.

I've read that ADAPT is linked to a lot of standards (ISO 11783, ISO 19156, etc.) How does this help me?

asasdd

How do I get access to the wiki?

When you visit the www.adaptframework.org site, you'll see a link to Model Documentation. That link leads to an ADAPT section in AgGateway's Public wiki space. You'll find a lot of information there. If you want a wiki account, visit the http://aggateway.atlassian.net site. You will see a login screen as shown in the figure below. Click on the "Create an account" link and follow the instructions.

Implementation Questions?

What are CompoundIdentifiers? 

Lorem ipsum dolor

How do I associate a GLN to a Manufacturer?

Andres Ferreyra and interns will address this. 

How do I associate a GTIN to a Product?

Andres Ferreyra and interns will address this.

asdasd

Why are times represented using the TimeScope class in some places, and a datetime timestamp in others?

lorem ipsum

Document and its child classes (Plan, Work Order, etc.) have several attributes (GrowerId, FarmId, FieldId, TimeScopes, etc.) that are also in the LoggedData and Summary objects that have an aggregation relationship with these Document child classes. Are LoggedData and Summary supposed to inherit the values of the parent Document?

No. The data shown in the document is supposed to be the UNION of the data in the child LoggedData / Summary objects. The original intent was for the lists of field references, etc. to serve as metadata that would help find documents of interest. The exception is the GrowerId, which is unique (the others are lists) and should be the same throughout the Document and its children.